Navigation: Rework categorization / grouping / TOC

[amotl]

Where "Overview of CrateDB integration tutorials" is referenced, we can work on the categorization similar to:

Originally posted by @marijaselakovic in #9 (comment)

[amotl]

Thank you for sharing your idea of categorization on behalf of this diagram, @marijaselakovic. Currently, we are bringing in the baseline on behalf of GH-29 and GH-34. We will be happy to look into your proposal together on a subsequent iteration.

[amotl]

Progress

There seems to be an upcoming proposal to rework the TOC based on entities from Diátaxis instead of mapping the landscape following a layout based on topic domains.

• Diátaxis - a systematic approach to technical documentation authoring #335
• https://github.com/crate/tech-content/issues/169

Pro

We think Diátaxis should be applied reasonably, because a significant amount of work has been invested to come up with a reasonable documentation architecture around CrateDB's topic domains, where the current TOC is based upon. Paradigms of Diátaxis seem to appreciate that in general.

Getting started with Diátaxis does not require you to think about dividing up your documentation into four sections. ¹

• https://diataxis.fr/how-to-use-diataxis/

In the absence of a clear, generalised documentation architecture, documentation creators will often try to structure their work around features of a product. This is rarely successful, even in a single instance. In a portfolio of documentation instances, the results are wild inconsistency. ² Much better is the adoption of a scheme that tries to provide an answer to the question: how to arrange documentation in general?

In fact any orderly attempt to organise documentation into clear content categories will help improve it (for authors as well as users), by providing lists of content types. ³

• https://diataxis.fr/map/

You can do what you like with Diátaxis. ¹

• https://diataxis.fr/start-here/#do-what-you-like

Con

NB: This should not be understood as stop energy to not come up with TOC proposals. However, adhering strictly to Diátaxis or any other fixed/generalized scheme on the topmost navigation level is a thing we have been actively refactoring away from during the last two years, so it would reverse all those operations.

A more difficult problem is when the structure outlined by Diátaxis meets another structure - often, a structure of topic areas within the documentation, or when documentation encounters very different user-types.

• https://diataxis.fr/complex-hierarchies/#two-dimensional-problems

• https://github.com/crate/tech-content/issues/144
• https://github.com/crate/tech-content/issues/145

We also don't think rearranging the TOC to a strict scheme provides a better user journey, because readers are mostly looking for useful information, and more often than not do not care too much about the form or paradigm it is written in, despite Diátaxis claiming differently in sections where it uses overly enthusiastic language.

• Improve general guidance aka. easy user journey #227

Footnotes

1. Full acknowledgement. ↩ ↩²

2. This is a claim without much substance, but we can talk about it. ↩

3. That reads much better. ↩

[amotl]

We are trying to accompany recent needs by trying to strike the balance between two styles of information conveyance, to swiftly mitigate the "two-dimensional problems" dilemma outlined above.

• README: Reflect new styles "learning path" vs. "reference material" #382
• Authoring guidelines: Mention "Diátaxis" approach crate-docs#117
• Naming things: Per Diátaxis, using "Guides" is not applicable. Use "Handbook" instead. crate-docs-theme#635