You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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. ↩
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
Idea
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 traditionalgetting-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: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
2Originally posted by @amotl in #168 (comment)
Footnotes
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. ↩
... like the dbt community tutorial absorption patch was starting to do it, see https://github.com/crate/cratedb-guide/pull/153#pullrequestreview-2515648242. ↩
The text was updated successfully, but these errors were encountered: