Suggestion: Loki (or really all LGTM) Docs

What I have found hardest about using all the awesome LGTM products is the difficulty in mapping versions of the various solutions to relevant/pertinent documentation in the docs website.

Specifically, it is extremely hard to tell whether advice on various pages still applies when a newer version of Loki comes out. For example with the release of tsdb it is not clear whether advice across the docs related to BoltDB continues to be applicable, or whether some parts of it have been superseded.

This is not an argument for deleting docs; obviously people are still using BoltDB, and need help as well, but with the rapid velocity of the improvement of your products, it does mean that sifting the documentation for those portions that are relevant to a specific setup of a version is harder than it could be.

One simple suggestion I’d like to make is to publish the “last change date” from the Git history onto the rendered pages of your documentation. That way it’s at least easier to determine whether a page has been recently updated to reflect newer features, or if it hasn’t been touched in a while.

It’d also be awesome to have more modular config documentation, because the one long single page spelling out all the settings across all the services makes it really hard to figure out which settings might be consumed by a Read or Write or Backend target as well.

In any case, thanks for the awesome software, and hopefully something here will spark some ideas on how to make it easier for newbies or less routine use-cases to figure out how to make this software work for them!

1 Like

As a user, I understand the desire to know if the documentation you’re reading is current and if it matches your environment.
As a technical writer, I can tell you that timestamping files does not guarantee that content is “fresh”. Here are some of the ways that someone might “touch” a file and update the timestamp, but that don’t necessarily mean that the content of the entire page has been reviewed for accuracy:

  • File is either entirely automatically generated or contains content that is automatically generated.
  • Fixing typos
  • Fixing formatting errors, for example YAML indentation.
  • Fixing broken cross references and links
  • Moving or renaming a file (the Logs, Metrics, and Tracing documentation is currently being rearranged into a consistent information architecture, which means moving and/or renaming all the files, even if the content is not being updated).
  • Small wording changes to match the Style Guide
  • Small changes to pass validation as we add automated linting to the various repos (Prettier, Vale, doc-validator).

There are technical writers working on the docs, but it’s more work than one person can do. As our documentation set grows, we need help from the community to keep the documentation up to date. If you find issues, log an issue against the docs. If you have the time to create a PR for the docs, even better!