New Resources for Contributors to the Grafana Project
Earlier this month, Ivana Huckova, one of Grafana’s junior developers, wrote an article about how to contribute to Grafana as a junior dev. As an open-source project supported by engineers around the world, Grafana strongly encourages anyone to contribute. And ICYMI, there are many opportunities to help: Testing the UI and reporting issues, finding and fixing bugs, and improving the documentation are just a few.
Have you checked Grafana’s Slack or GitHub repository lately? You might have spotted a few new resources to support new contributors, particularly for technical writers:
- New #docs Slack channel
- Contributing to Documentation
- Documentation Style Guide
- Glossary for commonly used terms
#docs Slack Channel
If you live in Slack like the rest of us, you know how useful it is to have a team to reach out to with questions and ideas. We created a Slack channel for anyone interested in learning more about Grafana, our documentation, and interacting directly with the core team.
Whether you want to inquire about an issue in GitHub you want to work on, or a missing doc that you want to create, the core team (and several volunteer contributors) are around to help.
Request your invite to join the public Grafana Slack channel here.
Contributing to Documentation
The improved general contributing guidelines, along with the Contributing to Documentation guide, answers the question that every contributor to open source has: Where do I start?
You’ll find several links to open issues that we currently need help with, including those tagged “beginner friendly” for anyone still getting a feel for the tool. It also provides a few guidelines, including how we structure and style content in the docs.
Documentation Style Guide
When you’re ready to really dig into the docs and make changes, it’s important to know what’s correct – and what’s a potential issue – style-wise. Our Documentation Style Guide, which lives on GitHub, provides the rules for the Grafana-specific style. Voice, tense, file-naming conventions, and word usage are all covered in this living document.
This style guide not only helps contributors who are documenting the areas of the Grafana tool from scratch, but also serves as a way to better identify inconsistencies in docs already written. Nearly all of Grafana’s documentation was developed before this style guide was made, so there are a lot of opportunities to help get every page on the same page, so to speak.
Calling All Docs Lovers!
Any good product needs excellent documentation to support its devs and users. In the Grafana 6.0 release, the UI got a significant update, but the documentation did not. This has left many graphics, walkthroughs, and details out of date or majorly fragmented. There are many sections where the format is inconsistent and doesn’t match other areas of the docs website.
Take a look at the Grafana Documentation website, then check out Grafana Play, which is a demo version of Grafana. The differences are quite apparent.
Want to help us out? The Contributing to Documentation Guide and Documentation Style Guide are there to get you contributing now, however you can. If you have a knack for documenting open-source projects (or want the chance to learn how), please give us a shout. Join the conversation in our “docs” Slack to get started.
Brenda Harjala is a technical writer who started contributing to Grafana’s documentation in September 2019, and immediately focused on making it easier for others to contribute as well.
