Contribute to documentation
How can I contribute to Grafana Labs documentation?
There are a number of different ways to contribute to documentation at Grafana Labs. Choose the one that applies best and learn how you can engage with the documentation team and help us by contributing your ideas.
Request a change
Request a change when you want to make a suggestion or provide feedback about a topic, but don’t want to provide an edit that generates a pull request.
Requesting a change gives you the freedom to express your ideas without committing language. Your suggestion can reflect a small change to wording or can reflect larger, more substantive changes.
GitHub captures your request as an Issue logged against the repository.
Note: You can only request a change against the latest release of documentation.
Before you begin
- Create a GitHub account.
To request a change:
From a topic on the documentation website, click Request doc changes.
The Issue title auto-populates with the location of the file for which you are requesting a change.
Click Submit new issue.
The Doc Squad determines the priority and scope of the change, and schedules the change to be made.
Edit a topic
If you want to recommend a small change, such as suggesting a correction to a topic, you can edit the topic directly in GitHub. You are not required to fork and clone the repository to use this approach.
Small changes might include:
- Adding steps to a task
- Adding clarifying language to a concept
- Providing an example
Note: You can only edit a topic that is part of the latest release of documentation.
Before you begin
- Create a GitHub account.
- Find the source repository. To find the source repository, refer to Find the source repository.
Find the source repository
Technical documentation published from public projects have a Suggest an edit link with a pencil icon. Click this link to directly edit the page in GitHub.
Warning: Because development happens in the
mainbranch on GitHub and “latest” documentation is typically published from a different “version” branch, the Suggest an edit link can result in a 404 error from GitHub. In that case, use the GitHub code navigation to try and find the new location or reach out to a Technical Writer for support.
For pages that do not have a Suggest an edit link, search the Grafana organization on GitHub for repositories that include the plugin name. For example, the Splunk data source for Grafana plugin, can be found by searching for “Splunk”.
/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/: Automatically generated and published from https://github.com/grafana/cloud-onboarding (Grafana Labs only). Integration documentation is generated from the metadata in https://github.com/grafana/cloud-onboarding/tree/main/integrations and the template file https://github.com/grafana/cloud-onboarding/blob/main/pkg/integrations-api/integrations/docs/templates/layout.tmpl.
To edit a topic
From a topic on the documentation website, click Suggest an edit (pencil icon).
Enter your changes.
Change the branch name, if required. The branch name is auto-populated.
Click Propose changes.
A PR is created and then goes through the PR review and approval workflow.
Develop a new topic
If you want to develop a new topic from scratch, you can create a documentation plan and collaborate with a member of the technical writing team. According to the book Docs for Developers, a documentation plan is a flexible outline for anticipating where the writing process will lead you.
Your documentation plan helps you to:
- Identify existing information gaps, and explain how you will fill them.
- Get feedback from users and stakeholders before the writing process begins.
- Consider different approaches you might take, and decide on one of them.
It is a best practice to have someone else test any task you have written. If another user can successfully complete the task using only the steps you have written, not guessing or using their inherent knowledge, then your task has passed the test. However, it is very common to find you have skipped steps because you are very familiar with the topic you are explaining.
New users or members of other teams are very helpful for these tests.
Review your changes
Prior to pushing your changes to GitHub, you can view a local build of the documentation so that you can review your work. For more information on using Git, refer to Use Git.
To view a local build:
Install either Podman or Docker to manage containers on your system.
Note: Podman has the upside that containers can either be run as root or in rootless mode.
If you are using Docker, start the Docker daemon if it is not already running.
Navigate to the project “docs” directory, this is typically
localhost:3002/docs/to review your changes.
Push changes and create a PR
When you are ready for other people to review your work, perform the following tasks:
Add your changes, which prepares your content for the next commit.
Commit your changes.
Push your changes to GitHub.
Create a PR in GitHub.
When writing the description for your PR, use GitHub keywords, for example “Fixes #1234”, to link your pull request to the issue and take advantage of GitHub automation for status updates and closing resolved issues.
type/docslabel, so the Docs team can track the issue.
The docs build system automatically conducts a series of tests to ensure that the content doesn’t conflict with other content in the docs repository.
PR review and approval workflow
When you add a PR to the repository and assign the
type/docs label, it will be reviewed by a member of the Docs Squad.
Depending on the size of the PR and the priority of other work, the PR will either be immediately reviewed and merged (minor fixes typically follow this pattern) or the PR will be triaged and placed in the backlog of work or moved into further development.
Contributing across versions
When you edit the
main branch of a project, it affects the content in the
next directory of the website.
To edit a previous version, or
latest (the most recent release), you must backport the changes into the long-lived version branches in the project repository.
To backport a change, use the
backport <vMAJOR.MINOR.x> labels on the GitHub pull request. For more information, see backporting.
grafanabot automatically creates a backport pull request after the original pull request is merged, if the merge commit can be cherry-picked without a conflict.
If this process fails due to a merge conflict,
grafanabot posts a comment explaining how to manually backport the change.