Jaeger v2 documentation

[Ashmita152]

Requirement - what kind of business use case are you trying to solve?

We started working on Jaeger v2 in other repositories. We should talk about Jaeger v2 from documentation perspective too. I think it will be great to revamp it as part of Jaeger v2 release.

Problem - what in Jaeger blocks you from solving the requirement?

Our documentation is great but not perfect. There is lot of knowledge which is in blogs or Gitter chat room which isn't on our documentation website.

Proposal - what do you suggest to solve the problem or improve the existing situation?

I am very new to documentation but I feel documentation plays a major role in success of any open source project or product.

I was looking at some open source projects documentation and the one I really like is https://vector.dev/. The one thing which I liked the most is "Guides" in their documentation.

I would like to hear your thoughts on it.

[Ashmita152]

Came across a Hugo theme: https://getdoks.org/

It has inbuilt support of "Blog" as well and look very neat.

[yurishkuro]

The problem with guides is that they get out of date even faster than the docs, because they are usually more detailed. To keep guides up to date, they really need to be tested step by step for every release. I'm not sure how to scale that process given limited resources in the project. At least when those are published as blog posts there is an implied assumption that the instructions work for a specific Jaeger version at the time of writing.

[Ashmita152]

Hi Yuri, Thank you for the feedback.

To keep guides up to date, they really need to be tested step by step for every release.

I think vector.dev uses https://cuelang.org/ for validating that documentation is up-to-date with the release.