Grafana Labs Writers' Toolkit: This is the way

At Grafana Labs, we understand that clear, informative technical documentation is critical to users’ success, whether they’re just getting started or trying to quickly troubleshoot an issue. That’s why the Documentation and Technical Writing Team at Grafana Labs is pleased to announce the launch of our very first, very own writers’ toolkit.

The Grafana Labs Writers’ Toolkit is designed to empower everyone to contribute to documentation at Grafana Labs, regardless of their function or role. So whether you work at Grafana Labs or are one of our many open source contributors from around the world, we want to help you produce the best documentation possible. 

At Grafana Labs, open source is in our DNA. As a result, we want to make it easier to contribute to our documentation. But we recognize that not everyone is a professional technical writer. The toolkit provides writing guidance and templates to make technical documentation easier. When you make a contribution, expect the technical writing team to then collaborate, with a focus on helping users best get the information they need. This frees up developer cycles to focus on building amazing technology that solves interesting problems. 

We use Google’s developer documentation style guide as our primary set of guidelines, because, let’s face it, they’ve done an excellent job and there is no reason to completely reinvent the wheel. 

The Writers’ Toolkit provides a unique set of style and writing guidelines that builds on top of that base and adds our unique brand, voice, and tone to the mix. It will enable us to produce consistent documentation with the same look and feel in a way that is easy to consume by our customers. 

And in addition to being fans of quality documentation, we’re also big fans of Star Wars. So with a nod to a galaxy far, far away, let’s dive into what you need to know about the Writer’s Toolkit.

What’s in the Writers’ Toolkit?

The Writers’ Toolkit consists of three main components:

• Style guide. In addition to adopting the Google developer documentation style guide as our primary source of editorial guidelines, we’ve included topics specific to Grafana Labs, including voice and tone and inclusive writing guidelines.
• Writing guide. The primary goal of the writing guide is to help you plan, write, and publish technical content. In this guide you’ll find all kinds of useful information to get started, including Markdown guidelines, guidelines for writing various topic types, information architecture guidelines, and so on.
• Templates. We’ve provided concept, task, and reference topic templates so you can get straight to the writing. Make a copy of a template Markdown file, add it to your branch, and dive in!

Scaling and supporting velocity

In the fast-paced and dynamic world of Grafana Labs, interesting and innovative ideas evolve very quickly. We want these innovative ideas to flourish, and doing so requires  good technical documentation. The Writers’ Toolkit empowers our development teams to write technical documentation that is consistent and focused on user goals, even if a professional writer can’t be fully involved in the project until a later date. 

Given our vast experience in technical writing, it just makes sense to share what we know with our contributors, both internal and external. The Writers’ Toolkit:

• Reduces friction so contributors avoid common pitfalls that make it difficult for others to find technical answers
• Ensures collaboration between the person who knows the most about their feature and the person who knows the most about presenting information
• Supports scalability by helping contributors plan and execute technical documentation projects
• Minimizes technical debt as draft content more closely aligns with technical writing best practices

Of course, the Writers’ Toolkit doesn’t address every aspect of building out our technical documentation, but it does move us forward quite powerfully. Internal response to the initial training has been extremely positive, and the request for more training has been consistent. We’re also including the training in our onboarding for new Grafanistas.

Develop a strong baseline of documentation

We organize our technical documentation in a simple, repeatable information architecture to ensure users can find what they’re looking for and contributors know what they should write. It’s intentionally simple, user-focused, correct, current, and consistent, with a clear structure that makes the documentation accessible when readers are seeking answers. To do so, we designed the Writers’ Toolkit to follow this organizational structure:

• Concepts that help readers understand through overviews of features and concepts associated with all Grafana Labs OSS projects.  
• Tasks that help readers do or learn through specific guidance
• References that help inform readers who want to better understand a full set of options

The Writers’ Toolkit supports all of these elements. By helping our contributors understand what we need and how to build it, we ensure we have comprehensive and accurate documentation that builds a strong baseline.

We’re committed to producing and maintaining the best technical documentation possible. In a little over a year, we’ve more than tripled our docs team and we continue to hire. The Writers’ Toolkit is part of that commitment, so we hope you find it useful. We look forward to you using it, and to your feedback as to how we can continue to make it even better!

Start helping today by contributing to Loki, Grafana, Tempo, or Mimir! The Writers’ Toolkit is for anyone who wants to contribute to Grafana Labs’ documentation, understand how we build documentation, or solve an interesting problem with their tech docs.