Harmonize leaf node page names: index.md vs. tutorial.md vs. usage.md

[amotl]

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 ¹ 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 ²

Originally posted by @amotl in #168 (comment)

/cc @kneth, @bmunkholm, @surister

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]

We've now organically started using learn.md as the canonical page name for the basic introductory tutorial about any given integration thing.

• https://cratedb.com/docs/guide/integrate/azure-functions/learn.html
• https://cratedb.com/docs/guide/integrate/dbt/usage.html <-- outlier, needs a fix! ;]
• https://cratedb.com/docs/guide/integrate/grafana/learn.html
• https://cratedb.com/docs/guide/integrate/influxdb/learn.html
• https://cratedb.com/docs/guide/integrate/marquez/learn.html
• https://cratedb.com/docs/guide/integrate/metabase/learn.html
• https://cratedb.com/docs/guide/integrate/mongodb/learn.html
• https://cratedb-guide--247.org.readthedocs.build/integrate/mqtt/learn.html

If there are no objections, we will populate this namespace slot with more existing material. Up until now, we are dealing with very much outdated material in cratedb-guide, while contemporary resources have been added on the community forum instead.

• Consolidate Integration Guides I vs. II #102
• https://github.com/crate/tech-content/issues/122

[bmunkholm]

For anything that is actually a tutorial, I think we should call it "Tutorial".

[amotl]

Thanks. Let's do a sweeping rename on the next iteration.

[amotl]

Instead of using learn.md, we now standardized on using tutorial.md per GH-250 for all subsections that only include a single/basic starter tutorial. Let us know if you would like to use another name as we go.

[amotl]

By learning from @surister about Diátaxis (thank you!),

• Diátaxis - a systematic approach to technical documentation authoring #335

we found the "naming things" operation towards tutorial.md was plain wrong, because many of those documents are mostly how-to guides about quick ramp-ups aka. walkthroughs, without following anything that would deserve the qualification of a curriculum or tutorial.

In this spirit, also in order to avoid using any of the possibly tainted names howto.md vs. tutorial.md, I am proposing to just standardize on usage.md, possibly paraphrased as "usage guide", unless anyone will come up with a better suggestion.

[amotl]

Hi again. We've implemented our proposal s/tutorial/usage guide/ on a few occasions already ¹ for demonstration purposes and it feels right. We will carry on doing so if there are no objections. Please tell us if you have any.

Footnotes

1. 12b2e14, b503656, ea5e730, c8adea6, 2fb99b0 ↩