Documentation Writers' Toolkit Get started

Get started with writing documentation

This guide includes everything you need to complete your documentation project from start to finish.

Goals

This guide:

• Teaches you how to successfully document products and features
• Provides a step-by-step guide from project kick-off to release
• Introduces you to the craft of creating good documentation

Audience

• Software developers who need to create documentation alongside code
• Other technical roles that create and contribute to documentation

Before you begin

• Consider what you want someone reading your documentation to understand or accomplish

Project checklist

If you have questions:

• and you are a Grafana Labs employee, reach out in the #docs channel on the internal Slack workspace.
• and you aren’t a Grafana Labs employee, reach out in the #docs channel on the community Slack workspace.

To get started:

1. Plan the work
2. Create the structure
3. Draft the documentation
4. Review the documentation
5. Publish the documentation

Plan the work

1. Decide what kind of documentation deliverables you need. What do you want a user to accomplish?

2. Know the release life cycle stage of the product or feature. Review the Release cycle for Grafana Labs.

Create the structure

1. Add documentation to your GitHub repository. Add a docs/sources directory to your repository, if it doesn’t already exist.

2. Create the folders and structure. Use the content framework for consistency across product documentation. For more information about the content framework, refer to Documentation structure.

Draft the documentation

1. Learn how to best write and organize your documentation. Read the topic types topic and sub-topics in the Writers’ Toolkit.

2. Add front matter. Read the front matter documentation.

3. Add images and media. Read the image, diagram, screenshot, and video guidelines documentation.

4. Use links. Refer to the links documentation.

5. Add code samples. To add samples with Markdown, refer to Code blocks. For style guidance, refer to Code examples. For samples in multiple languages, refer to Code.

6. Refer to the Style conventions.

Review the documentation

1. Build the documentation locally. For instructions, refer to Test documentation changes.
2. Open a pull request and use the label type/docs.
3. Use doc-validator and the Vale prose linter. These are often automatic checks from within the PR itself. To learn more about [doc-validator], refer to Automated validation with doc-validator. To learn more about the Vale prose linter, refer to Lint prose with the Vale linter.

Publish the documentation

1. Review publishing options. If you are a Grafana Labs employee, reach out in the #docs channel on the internal Slack workspace. If you aren’t a Grafana Labs employee, reach out in the #docs channel on the community Slack workspace.
2. Backport, if required. For guidance, refer to Backport changes.
3. Add What’s new or release notes, if required. For guidance, refer to Contribute to What’s new or release notes.