Menu
DocumentationWriters' ToolkitGet started
Open source

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, you can ask them in the Grafana Community Slack #docs channel.

1. 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.

2. Create the structure

  1. Add docs 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.

3. 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, and screenshot 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 guide.

4. Review the docs

  1. Build the docs 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.

5. Publish the docs

  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.