Get started with Writers’ Toolkit
This guide includes everything you need to complete your documentation project from start to finish. In short, it quickly points you in the right direction.
Goals
By reading this guide, you will:
- Learn how to successfully document new products or features
- Have a step-by-step guide from project kick-off to release
- Be introduced to the craft of creating good documentation
Audience
- Software developers who need to create docs alongside code
- Other technical roles that create and contribute to docs
Before you begin
- Consider what you want someone reading your documentation to understand or accomplish
Project checklist
If you have questions, you can ask them in the Grafana Community Slack #docs channel.
1. Plan the work
Decide what kind of documentation deliverables you need. What do you want a user to accomplish?
Know the release life cycle stage of the product or feature. Review the Release cycle for Grafana Labs.
Consider content reuse, if applicable. Read the Reuse strategy documentation.
2. Create the structure
Add docs to your GitHub repository. Add a
docs/sources
folder to your repository, if it doesn’t already exist.Create the folders and structure. Use the content framework for consistency across product docs.
3. Draft the docs
Learn how to best write and organize your docs | Read the topic types topic and sub-topics in the Writers’ Toolkit.
Add front matter. Read the Front matter documentation, and other key information to Hugo (our publishing platform).
Add images and media. Read the Images and media documentation.
Use links and references. Refer to the Links and references documentation for guidance.
Add code samples. Refer to the Code samples documentation for guidance.
Refer to our Style guide.
4. Review the docs
Build the docs locally. Refer to the build locally guidelines and check for errors, particularly in linking.
Open a PR and tag the docs team. Use the label type/docs.
Use
doc-validator
and Vale linter. These are automatic checks from within the PR itself. Learn more about thedoc-validator
and the Vale linter.
5. Publish the docs
Review publishing options. Engage #docs to discuss the publishing options for different stages in the release cycle.
Backport, if required. Refer to the backporting guidelines.
Add What’s New or release notes, if required. Refer to the Contribute to release notes guidelines. In Grafana, use the label
add-to-whats-new
in your PR.