Re-organize overlapping sections (Concepts, Best Practices, Tutorials, Guides, Specifications)

[beorn7]

Disclaimer: This proposes an incremental change to how we organize content on the docs site. This cannot be perfect, but the fundamental revamp of the docs site hasn't happened in years, so we better stop the bleeding with simpler steps._

We have quite a lot of top level sections on the docs sites, and some of them are overlapping and also quite fuzzy so that users won't have an idea where to look for what. I'm mostly thinking about Concepts, Best Practices, Tutorials, Guides, and Specifications. One might argue that these terms have clean definitions, but for one, I don't think that we can expect the majority of users to know them, and worse, we aren't even consistent about them in practice. My attempt on definitions, with some thoughts about the problems:

• Specifications are pretty clear, I guess. They are "hard" specs as we know them from IETF RFCs etc. There are only two entries in this section so far (both about remote write), and they fit the definition quite well. However, in Add native histogram specification #2539, I'm currently adding the native histogram "spec". However, it is only partially a spec. It's bleeding dangerously into explaining concepts. Segue to…
• Concepts are, I guess, different from specifications as they focus more on explaining things rather than just specifying. However, the Data model sub-section is still pretty close to a specification. Metric types might be a good example for an actual concept, while Jobs and instances bleeds into something that feels more like Prometheus server documentation.
• Best Practices has many sub-sections that deserve the name, but Remote write tuning could also be seen as a guide. Histograms and summaries has a lot of "concept" parts, but also gives you practical advice, which could qualify it as a "guide". I'm planning to write a contributor's guide and a Go style guide. Both have the word "guide" in their name, but they might actually fit better in the Best practices section (at the very least for the Go style guide).
• Guides are meant to guide the user towards some practical tasks, but not in a "step by step" fashion, because that would be a Tutorial, i.e. the main differentiator between the two. However, the very first Guide (Basic auth) literally has the following note close to the top: "NOTE: This tutorial covers basic auth connections [...]". In practice, it's really hard to draw the line between Guides and Tutorials. Interestingly, we have a "guide" Instrumenting a Go application and a "tutorial" Instrumenting HTTP server written in Go. They have really subtle differences in focus, but I claim it would probably be better to merge them both into the same document. In the other direction, some "guides" are actually important over-arching documentation and almost bleeding into "concepts" or "best practices" (UTF-8 in names, OTel integration, …).
• Needless to say that we also have the blog, which sometimes features articles that would easily fit into one or more of the other sections described here.

I don't have a silver bullet to propose, but I think it would reduce the confusion if we had fewer sections. Some ideas:

• We recently extracted the RW specs out of Concepts, but given that there are so few entries in both Concepts and Specifications, how about merging both into Concepts and Specifications, maybe making sure that "formal" specs like the RW ones have the word "specification" in their sub-section title.
• I think we should get rid of the headline Guides as it is so ambiguous (cf. "style guide", "contributor's guide"). Let's move all "tutorial"-like entries to the Tutorial section. Maybe call the latter How-Tos" as a wider term? Maybe move some Best practices entries there as well. And then things like code style guides and a contributor's guide could better fit into Best Practices.

I hope we can collect same thoughts and discussions here before somebody invests the effort to create a PR.