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.

[henrik-caesar]

Hello guys,
My name is henrik Caesar, and I have 15+ years experience as Product Manager in the "monitoring area". I recently started looking at Prometheus more seriously (I started experimenting some years ago), and found the documentation had some room for improvement, specially for the beginner. After some discussion in slack with Bryan Boreham and Matthias Rampke I decided to make an attempt at a new intro document for beginners that I can share with you (obviously overlapping with much that already exists, but structured in a different way). I think I could help with improving the documentation in general, if you are interested.
What do you think?
BR Henrik

[beorn7]

Thanks @henrik-caesar for your offer to help. There is definitely a lot of room for improvement when it comes to docs.

Note, however, that this particular issue is not about adding the desperately needed intro document. It is more about an incremental change to the structure. Plus, it is only a proposal that I put here to get feedback or even buy-in from those that are more qualified than myself when it comes to our website. That hasn't even happened yet.

If I understand you correctly, you would like to start with a new intro document. Discussing the details of which should not happen on this issue, and not primarily with me, as I'm not one of the docs maintainers. I suggest to ask for feedback and advice on community channels (like #prometheus-dev on CNCF Slack) and/or directly get in touch with the docs maintainers.

If you already have a draft ready for the intro doc (which you seemed to have discussed with @bboreham and @matthiasr already), then you could also just create a PR and take it from there.

[henrik-caesar]

Yes, I was thinking about restructuring/cleaning/updating the existing documentation too. Booth are needed I think. I'll bring it up on slack then , and contact doc maintainers. (Thanks for that)