I guess we could have reference-style documentation and more tutorial-style documentation on the same site, but clearly separated.
Arguably, we already have that with the Guides section. However, I don't think that this section is well advertised. The flow through the site is in general not very obvious or smooth. I could imagine, for someone completely new to the site, it's very hard to find the right thing by something else than using a search engine to jump directly to parts of the site. This problam _also_ affects the pure reference part. Examples: - As said above, what are "Guides" even? How do I see that that's a good way to find some cookbook-style advice? There is "First steps", but it doesn't link to the Guides. - Then there isn "Best Practices". In what way are those different from "Guides"? Again, there is no overall guide through the site. The landing page has those eight section it points to, and a Get Started pointer, but none is to Guides or Best Practices. - The site is not very clear what is prometheus/prometheus AKA "the Prometheus server" and what is general Prometheus ecosystem and what are Prometheus components like the Alertmanager. For example, if I click "Get Started" on the landing page, I get to the "Getting Started" section of the prometheus/prometheus documentation. Perhaps the "First steps" section in the Introduction would make more sense. But the latter is anyway (perhaps?) an outdated version of the former? The section about the Prometheus server is simply called "Prometheus", but that's what the whole site is about, isn't it? - Another example for the previous item: alerting. The "Precise Alerting" link on the landing page goes to the Alerting Rules section two levels deep in the prometheus/prometheus documentation. However, there is a top-level section "Alerting", which is also relevant. It is mostly concerned with Alertmanager (which is not obvious from the section titel) but also contains a sub section "Alerting overview" (which is probably where I'd naively expect the landing page link about alerting pointing to. - Another flow problem: If I am in the "Prometheus" section, there is a subsection "Management API". However, if I'm looking for the TSDB admin API, I won't find anything there, but instead I have to click on "Querying" and then "HTTP API". -- Björn Rabenstein [PGP-ID] 0x851C3DA17D748D03 [email] [email protected] -- You received this message because you are subscribed to the Google Groups "Prometheus Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-users/20200316180735.GP14683%40jahnn.
