Naming things: Per Diátaxis, using "Guides" is not applicable. Use "Handbook" instead.

[amotl]

About

I think we agree that "Guides" is wrong according to Diátaxis. Why not just use "Handbook", as it's a neutral term, not tainted too much, and easily understandable. In the absence of a better proposal, we may just go ahead and give it a try for a while. Renaming the repository and the URL entrypoint can optionally follow on a subsequent iteration.

[surister]

I wouldn't consider it wrong? Why would it? The issue is that we have content withing guides that are not guides, but I don't think we solve that by changing the name of the section, but slowly fixing/adding the content

[amotl]

Hi. This repository was intended to be a handbook-style documentation, and sure it also includes some how-to guides and even some articles that remotely qualify as tutorials according to Diátaxis. This patch is here to purposefully move away from positively tainted nomenclature on the top-level labels, so any refactoring operation will not be rooted within a single school. The intention is that the ingredients can support multiple schools at the same time.

• Diátaxis - a systematic approach to technical documentation authoring cratedb-guide#335
• Navigation: Rework categorization / grouping / TOC cratedb-guide#10

[amotl]

GH-627 even intends to remove the top-level heading label completely, so it is another signal it should omit certain semantics as good as possible. We didn't want to make the label determine its ingredients, so with the new orientation towards Diátaxis, it should dearly be renamed, to be out of the way on those spots.

[bmunkholm]

Ideally we could come up with something better, as "handbook" doesn't really mean much?
The problem is likely a different one, that the collection of pages within "guides"/"handbook" likely could be split out differently into the TOC itself in other more meaningful collections. So we can either persue that reorg or temporarily use Handbook - I'm fine with that.
Any objections @surister @kneth ?

[amotl]

Yes. "Handbook" is the proposal now because it doesn't mean anything specific on purpose. "Guide" has been tainted a bit by Diátaxis' meaning of "how-to guides".

[bmunkholm]

Replaced by #627