Discussion: distinguish between guide-level and reference-level documents

[stdrc]

Currently we put detailed syntaxes for "Join", "Time Windows", "Window functions", etc. in the top-level "Manage data" section. At the same time, we have other features only having documents in "Develop - SQL references" section.

Seems when writing these docs, we don't exactly know where to put which page in. An example is that we have /sql/functions-operators/sql-function-time-window.md displaying in "Manage data - Transform & query data", because it's both a guide-level document and a reference-level document...

I want to propose an idea that we should distinguish between guide-level documents and reference-level documents.

• A guide-level document should briefly describe a feature or a practice that can be done in our system, with one or more easy-to-understand examples, serving as a guide.
• A reference-level document should document every possible detail of public syntaxes and behaviors, serving as a reference.

A very good example for the separation of these two kinds of documents is Indexes and CREATE INDEX, the former being a guide-level doc and the latter being a reference-level doc.

[stdrc]

@xxchan Do you have any insights on this?

[xxchan]

SGTM. Would you like to draft a more detailed outline?

[xxchan]

BTW, I think this is somehow similar to the tutorial https://github.com/risingwavelabs/risingwave-docs/issues/2355

[st1page]

just found an interesting theory https://docs.divio.com/documentation-system/structure/