Why does Grafana's (all products) documentation suck so much? Serious question

Site Feedback
1

Not trying to be a troll or a impolite here, but compared to everything else I’ve used in the past, this (“Technical documentation” at Technical documentation | Grafana Labs) has to be some of the worst stuff I’ve ever come across. Almost as if it’s purposely written to be confusing.

It’s extremely difficult to make sense of, and nearly impossible to find what you need. Most of the time you are going around in circles. You click on a link hoping to find an expanded description of a topic only to be disappointed by being shown something completely unhelpful or off topic, then pointing you back to where you came from. Or worse, pointing you to yet another useless page that brings you back to the beginning.

There are very little concrete examples showing common use cases and best practices. In your documentation website, the directives/parameters for the configuration files are poorly documented. They explain nothing about what the directive does. Possible values are rarely provided or explained (or they are difficult to find). I often find myself having to resort to using a 3rd party site to get the information I need from some random stranger who went through the same problem but was kind enough to share his findings. I shouldn’t need to do that.

Here’s an excellent example: prometheus.scrape | Grafana Alloy documentation

On that page, how would someone know how to configure multiple scrape targets for the prometheus.scrape component? All it says is that the targets are of the format list(map(string)). That’s not helpful. Perhaps consider adding a column with an example, or a link to a page with examples.

Another problem is that everything assumes you are using k8s or Docker. Please stop making those assumptions, some UNIX OS’s don’t work with Docker or k8s. Make the simple configuration examples for a basic standalone Linux/Unix target system the “first class citizen” so that the concepts are understood, then introduce the more complex stuff.

So far I’ve only mentioned the configuration of individual services. It gets so much worse when you want to have the stuff talking to each other.

It’s so bad that not even AI models are capable of making sense of it. I think you guys need to take a serious look at what you have and rethink it. It’s not working.

2

I honestly think a serious question about the title needs serious research.

First, I’m missing the definition of “perfect documentation”.

Let me guess. “Perfect documentation” is documentation, which covers all possible use options.

Let’s do a serious math. Let’s say we want to have 4 supported OSs:

FreeBSD
Linux
Windows
MacOS

Each OS can have ~3 suported releases.

Each instance can have ~8 different deployment options:

package
binary
docker
docker compose
docker desktop
K8S
nomad
rancher

Let’s assume that app can have 700 config binary options (for example Grafana has 783 config options and the majority of them are not just binaries - grafana/conf/defaults.ini at main · grafana/grafana · GitHub)

Let’s assume we support 3 major app releases.

Let’s write app doc for each option, serious math:

4 * 3 * 8 * 700 * 3 = 201600 doc pages

This is simplified math. Let’s say we will find someone, who will write those doc pages. Will you (or AI) be able to find what you need in this case? IMHO you already provided the answer:

It’s extremely difficult to make sense of, and nearly impossible to find what you need.
It’s so bad that not even AI models are capable of making sense of it.

Actually, there are many more options, so “Perfect documentation” will grow exponentially - serious deployment can be: Use terraform, which will deploy helm chart via Argo-CD on K8S (so 4 different tools, just to deploy the app and each of them has different options).

My recommendation: be familiar with each (underlying) tool/syntax, which you want to use - learn those basics and then you will be fine. In this particular case be familiar with Prometheus.
Of course, it can be “time-wasting” for some people, so they have still the option to pay for Grafana support (I work a lot with them, so I recommend those guys).