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).

3

Here’s another excellent example: grafana/docs/alloy/latest/troubleshoot/debug/

Lets say search Google for “enable Grafana Alloy UI”. I arrive at that page above. I read through the page and reach the section that says

Alloy includes an embedded UI viewable from the Alloy HTTP server, which defaults to listening at http://localhost:12345.

Underneath that I see:

To expose the UI to other machines on the network on non-containerized platforms, refer to the documentation for how you installed Alloy.

Then underneath that I see

If you are running a custom installation of Alloy, refer to the documentation for the alloy run command to learn how to change the HTTP listen address, > and pass the appropriate flag when running Alloy.

So which do I click? I decide to click both.

I arrive at

  • grafana/docs/alloy/latest/set-up/install/ (Install Grafana Alloy)
  • grafana/docs/alloy/latest/reference/cli/run/ (The run command)

First page, I’m shown a list of options/platform on how to install Alloy, but hey I already have Alloy installed. I just want to enable the Web UI. Why am I taken here? Oh well, I click “Install Grafana Alloy on Linux”, that takes me to grafana/docs/alloy/latest/set-up/install/linux/. Nothing on that page tells me want I want. At the bottom I’m shown two options “Run Alloy” and “Configure Alloy”. Which one do I click? I don’t know. I click both.

I now have 4 tabs open.

I return to my second tab “The run command”. Lots of information on that page, but I don’t see what I need. Maybe it’s there? but I’m frustrated at this point and I still have 2 other tabs to look at. I close this tab and move to the next one

“Run Grafana Alloy on Linux” (Run Grafana Alloy on Linux | Grafana Alloy documentation). Nothing there tells me what I need to know. … frustration builds further.

Next tab

“Configure Grafana Alloy on Linux” (grafana/docs/alloy/latest/configure/linux/). There it is all the way at the bottom. Finally found what I need after nearly a half hour.

1 Like