search

jaegertracing / documentation

Documentation/website for the Jaeger Distributed Tracing project.
https://jaegertracing.io/
Apache License 2.0
67 stars 160 forks source link

Jaeger v2 documentation #486

Open Ashmita152 opened 3 years ago

Ashmita152 commented 3 years ago

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 commented 3 years ago

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

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

yurishkuro commented 3 years ago

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 commented 3 years ago

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.