Fix documentation menu

[lfrancke]

This is done when

• the "Architecture" link in the blue bar either points to content or is removed, at the moment it just points right back at the overview
• Most non-specific content is hidden behind the "Getting Started" link which also doesn't make sense, renaming it to "Platform Documentation" or just "Documentation" should help for now.

[fhennig]

I've looked at this https://diataxis.fr/ for a while now, since you dropped the link in a meeting some time. I have also looked at other documentation that I liked, and had some thoughts on how we can improve our documentation.

First, I really like the division into Tutorials, Guides, Explanation and Reference. The Getting Started Guide is a tutorial, it is not intended for production use and instead is useful for learning. Our operator docs are mostly reference, where the reader can look up specific config settings etc. Our ADRs are something where we could derive "Concepts" from, which would fall into the Explanation category.

I think the docker and kubernetes docs are really good: Docker, Kubernetes.

On both they these tiles on the front page, making it easy for the reader to find what they are look for, I think that would be good to have for us too. Basically the menu entries again, but with some descriptive text so it's easy to find what you need.

For kubernetes, we can see the same 4 segments as well: Understand Kubernetes (explanation), Try Kubernetes (Tutorials), Learn how to use Kubernetes (guides) and Look Up Reference Information (reference).

---

Coming back to this ticket, I think "Architecture" should probably be called "Concepts", but we don't have any content for that yet I believe. But for example in the zookeeper docs, there is already some conceptual writing about the discovery mechanism, which we could put in a dedicated concept article. Same for our s3 object system, and the way we integrate OPA.

The "Supported Product Versions" is specific reference information, that I would put in a reference section. "Monitoring" is a Guide for a specific task (like the Kuberentes "Tasks" section) and that should probably get it's own section too and contributors guide could also be it's own top level thing, like with kubernetes.

So, I think the top level elements should be "Overview", "Getting Started", "Concepts" (But there's nothing there yet), "Tutorials", "Tasks", "Reference", "Contributing".

• The getting started guide can stay in getting started
• "Monitoring" moves to the Tasks section
• "Supported product versions" move to the Reference section
• "Contributors Guide" gets its own top level link
• Our operator docs go into the reference information
• Our docathon result (not linked yet) can go into the tutorials section (Update documentation menu for docathon results #179)

Maybe we won't have much more cluster-general tasks like the "Monitoring" article, so Tutorials and Tasks could also be just one top level thing maybe.

[fhennig]

I'll make a pull-request for this @lfrancke if you don't mind