Hello Everyone! The current OpenTracing website has grown long in the tooth. Now that the OpenTracing API is stabilizing, it’s time to give the documentation an overhaul. We’ve identified two main issues that could help with this.
The first is that the current website, written in Jekyll, was too hard to edit. On a clean macbook, it would take ~1.5 hours to load up everything needed to get the site running locally. Boooo.
To solve this, OpenTracing is getting a new website. We’re switching from Jekyll to Hugo, which works in a similar manner, but allows users to get to work just by downloading a single binary. Big shout out to Luc Perkins for making this happen!
The second issue is developing much more in-depth documentation. In addition to high-level documentation that explains basic OpenTracing concepts and terminology, we see the need for language-specific documentation which demonstrates many of the common scenarios users encounter when instrumenting their code. Think of it as an OpenTracing cookbook full of tracing recipes.
Last but not least, we want to explain tracing in general, including the parts that OpenTracing specifically does not touch — wire protocols and the like — along with clear explanations for why these are not included as part of the OpenTracing project. The tracing landscape is fairly fractured, and if OpenTracing became the best place to learn about tracing in general, it would be a boon to the community. Explaining each component of a tracing system, what options are available, and why things are divided up they way they are, will be part of the new website.
So, to kick-start the new documentation initiative, we’d like to bring together API maintainers, writers, and community members for an all-day documentation hackathon. Details are below.
When: Wednesday, June 13th
Where: Gitter, with live meetups in San Francisco, Boston, Munich, and (possibly) Austin. Start time and addresses TBD.
How it works:
First, download Hugo, then git clone the OpenTracing website and check out the v2.0 branch. That’s all you need to do to get started.
We’ll be using GitHub to manage the documentation backlog. Find the issue for each piece of documentation you want to work on, look at who else is assigned and start collaborating. Once you’re ready for an editorial review, make a PR. It’s that easy! Writers, organizers and domain experts will be available to answer questions.
To be clear, there’s no need to be a great writer to write documentation! We’ll assist in cleaning it up and polishing everything. The most important part of this exercise is to get a brain dump of all the knowledge in the OpenTracing community into a central repository of knowledge. If there’s ever been a piece of documentation you wish existed when you were learning about tracing