Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Harmonize "naming things": Leaf node page names -- index vs. tutorial(s) #171

Open
amotl opened this issue Dec 21, 2024 · 0 comments
Open

Comments

@amotl
Copy link
Member

amotl commented Dec 21, 2024

Idea

Suggest to move the tutorial page to docs/integrate/marquez/tutorial.md.

Thoughts

Of course, we are always happy about any suggestions in this area, for example to shape the leaf node levels of our documenation tree into a form that adheres to certain conventions. In this case, we could also use a canonical name like start.md for this page, as a shorthand surrogate for the traditional getting-started.md.

In this spirit, those reshapings 1 are intended to establish a very simple page structure + leaf-node backbone semantics + URI scheme for all sections at doc/guide/integrate/<name> like:

File What's Inside
index.md Product card and general introduction.
canonical "tutorial.md" Traditional hands-on "getting started" usage tutorial.
otherpages.md Any other tutorials or pages that might become relevant for the integration topic at hand.

Particularly here, I am trying to find a good canonical name for the main "getting started" tutorial, because this very detail has not been nailed yet. A few good candidates could be:

  • learn.md
  • start.md
  • tutorial.md
  • usage.md 2

Originally posted by @amotl in #168 (comment)

Footnotes

  1. I need a few more rails for refactoring more content from the tutorials in the community forum, that's why I am using the chance to elaborate about those details here, in order to gather feedback about them. We will replicate the decision made here many times, and renaming pages is daunting, also because of Cool URIs don't change, that's why I am trying to give it a chance to be sorted out collaboratively and, most important, sustainably.

  2. ... like the dbt community tutorial absorption patch was starting to do it, see https://github.com/crate/cratedb-guide/pull/153#pullrequestreview-2515648242.

@amotl amotl changed the title Naming things for better rails: Leaf node page names -- index vs. tutorial(s) Harmonize "naming things": Leaf node page names -- index vs. tutorial(s) Dec 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant