OpenTracing Website Update

We’re happy to announce that opentracing.io has been updated to version 2.0! This is the first major update to the OpenTracing website since it was created, and I’d like to go over what the changes mean for our community.

First, though, let me offer heartfelt thanks to everyone who contributed to getting v2 launched: @lucpersons @tedsuo @isaachier @JStickler @burnington @black-adder @carlosalberto @alex-ls @austinlparker @PikBot and many more who have contributed to the website over time.

Site Overview

The first thing you’ll notice on the new site is that we reorganized our information to make it more approachable and consistent. Overall, one of the biggest goals in the site redesign was to structure information in a more accessible and easily understood way. To that end, we focused on the following four use cases:

• Quick Starts and Tutorials: Working code that you can drop in to begin using OpenTracing.
• Overviews: High-level, conceptual overviews of OpenTracing and its components.
• Best Practices: Practical insights into the application of OpenTracing for real-world design challenges.
• Guides: In-depth, language-specific usage manuals for OpenTracing that map general concepts to specific, actionable examples.

Let’s talk about what you’ll find, starting with our revamped documentation page.

Docs

The main documentation page is the place to start learning about OpenTracing. There’s a quick-start introduction, an in-depth overview of the concepts of Distributed Tracing and its components, and finally a guide to best practices and common use cases for both application and framework developers.

Guides

Guides are intended to be a collection of in-depth information about how to use OpenTracing, beyond a simple ‘Hello, World’. We’ve broken these guides down by language, so there’s a single place to discover practical and in-depth information on how to use OpenTracing for its supported platforms. We’d love to have your contributions as part of these docs — check out the opentracing.io repo on GitHub and submit a pull request.

Project Information

The OpenTracing specification and related documents now have a home on opentracing.io as well. You can read the spec, understand the governance model and project organization, read about the semantic conventions, and see what’s changed — all without navigating to multiple repositories.

Get Involved

Interested in contributing? We’ll tell you how. This section of the site includes information on how to propose additions or changes to the OpenTracing specification, how to join a working group, and how to add your plugin or extension to our list of external contributions.

Easy To Contribute

Previously, the website was built on the Jekyll static site generator. While this tooling worked, it could be cumbersome to install the required dependencies, especially for first-time contributors.

By moving to Hugo, we were able to reduce the dependencies for local development down to a single, precompiled hugo executable.

Now, adding new guides or documentation is as straightforward as adding a new markdown page to the repository and opening a pull request. Hugo will automatically add the new content to the correct menu and section. We’re actively looking for more guide content, so head on over and contribute.

Looking Forward

We’re especially excited about this new iteration of our documentation and hope that it makes it easier to use and discover information about OpenTracing. This isn’t the end of our work, though, it’s just a new beginning. We’re already starting to work on adding a searchable registry of tracers and plugins from independent contributors that we hope to ship soon. While we’ve launched with several guides in a more-or-less complete state, we have gaps. The C#, Golang, JavaScript, Ruby, and Service Mesh guides all have some stub sections that need to be filled out.

Our goal is to become the best resource on understanding and implementing Distributed Tracing, but to do that, we need your help. Check our list of open issues, see if there’s anything you’d be interested in working on, and make a PR. We’ve also got a channel dedicated to documentation on our Gitter, so feel free to ask any questions you might have there.

Happy Tracing!