2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2022-01-26 12:08:38 +05:30
# How to update GitLab documentation
2018-11-20 20:47:30 +05:30
2022-01-26 12:08:38 +05:30
Anyone can contribute to the GitLab documentation! You can create a merge request for documentation when:
2019-12-21 20:55:43 +05:30
2020-05-24 23:13:21 +05:30
- You find errors or other room for improvement in existing documentation.
- You have an idea for all-new documentation that would help a GitLab user or administrator to
accomplish their work with GitLab.
2019-12-21 20:55:43 +05:30
2022-01-26 12:08:38 +05:30
If you are working on a feature or enhancement, use the
[feature workflow process described in the GitLab Handbook ](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change ).
2019-12-21 20:55:43 +05:30
2020-05-24 23:13:21 +05:30
## How to update the docs
2019-12-21 20:55:43 +05:30
2022-01-26 12:08:38 +05:30
If you are not a GitLab team member, or do not have the Developer role for the GitLab repository, to update GitLab documentation:
1. Select an issue you'd like to work on.
- You don't need an issue to open a merge request.
- For a Hackathon, in the issue, in a comment, mention the person who opened the issue and ask for the issue to be assigned to you.
To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue.
If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale ](testing.md#vale ) issues.
1. Go to the [GitLab repository ](https://gitlab.com/gitlab-org/gitlab ).
1. In the top-right, select **Fork** . Forking makes a copy of the repository on GitLab.com.
1. In your fork, find the documentation page by going to the `\doc` directory.
1. If you know Git, make your changes and open a merge request.
If not, follow these steps:
1. In the top right, select **Edit** , make the changes, and **Save** .
1. From the left menu, select **Merge requests** .
1. For the source branch, select your fork and branch. If you did not create a branch, select `master` .
For the target branch, select the [GitLab repository ](https://gitlab.com/gitlab-org/gitlab ) `master` branch.
1. For the commit message, use 3-5 words, start with a capital letter, and do not end with a period.
1. Select **Commit changes** . A merge request opens.
1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one.
If you need help while working on the page, view:
- The [Style Guide ](styleguide/index.md ).
- The [Word list ](styleguide/word_list.md )
- The [Markdown Guide ](https://about.gitlab.com/handbook/markdown-guide/ ).
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
### Ask for help
Ask for help from the Technical Writing team if you:
2019-12-21 20:55:43 +05:30
- Need help to choose the correct place for documentation.
- Want to discuss a documentation idea or outline.
- Want to request any other help.
2021-03-11 19:13:27 +05:30
To identify someone who can help you:
2020-01-01 13:55:28 +05:30
2020-04-22 19:07:51 +05:30
1. Locate the Technical Writer for the relevant
[DevOps stage group ](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ).
2020-01-01 13:55:28 +05:30
1. Either:
2020-03-13 15:44:24 +05:30
- If urgent help is required, directly assign the Technical Writer in the issue or in the merge request.
2020-01-01 13:55:28 +05:30
- If non-urgent help is required, ping the Technical Writer in the issue or merge request.
2021-02-22 17:27:13 +05:30
If you are a member of the GitLab Slack workspace, you can request help in `#docs` .
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
## Documentation labels
When you author an issue or merge request, you must add these labels:
- A [type label ](../contributing/issue_workflow.md#type-labels ).
- A [stage label ](../contributing/issue_workflow.md#stage-labels ) and [group label ](../contributing/issue_workflow.md#group-labels ).
For example, `~devops::create` and `~group::source code` .
- A `~documentation` [specialization label ](../contributing/issue_workflow.md#specialization-labels ).
A member of the Technical Writing team adds these labels:
- A [documentation scoped label ](../../user/project/labels.md#scoped-labels ) with the
`docs::` prefix. For example, `~docs::improvement` .
- The [`~Technical Writing` team label ](../contributing/issue_workflow.md#team-labels ).
- A type label: either `~"type::feature"` or `~"type::maintenance"` .
2019-12-21 20:55:43 +05:30
### Reviewing and merging
2022-04-04 11:22:00 +05:30
Anyone with the Maintainer role to the relevant GitLab project can
2021-09-04 01:27:46 +05:30
merge documentation changes. Maintainers must make a good-faith effort to ensure that the content:
2019-12-21 20:55:43 +05:30
- Is clear and sufficiently easy for the intended audience to navigate and understand.
2021-01-29 00:20:46 +05:30
- Meets the [Documentation Guidelines ](index.md ) and [Style Guide ](styleguide/index.md ).
2019-12-21 20:55:43 +05:30
If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant
2020-04-22 19:07:51 +05:30
[DevOps stage group ](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ).
2019-12-21 20:55:43 +05:30
The process involves the following:
- Primary Reviewer. Review by a [code reviewer ](https://about.gitlab.com/handbook/engineering/projects/ )
or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped
for minor fixes without substantive content changes.
2021-11-18 22:05:49 +05:30
- Technical Writer (Optional). If not completed for a merge request before merging, must be scheduled
2020-01-01 13:55:28 +05:30
post-merge. Schedule post-merge reviews only if an urgent merge is required. To request a:
2019-12-21 20:55:43 +05:30
- Pre-merge review, assign the Technical Writer listed for the applicable
2020-04-22 19:07:51 +05:30
[DevOps stage group ](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ).
2020-01-01 13:55:28 +05:30
- Post-merge review, see [Post-merge reviews ](#post-merge-reviews ).
2019-12-21 20:55:43 +05:30
- Maintainer. For merge requests, Maintainers:
- Can always request any of the above reviews.
- Review before or after a Technical Writer review.
- Ensure the given release milestone is set.
- Ensure the appropriate labels are applied, including any required to pick a merge request into
a release.
- Ensure that, if there has not been a Technical Writer review completed or scheduled, they
2021-11-18 22:05:49 +05:30
[create the required issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review ), assign it to the Technical Writer of the given stage group,
2019-12-21 20:55:43 +05:30
and link it from the merge request.
The process is reflected in the **Documentation**
2021-09-04 01:27:46 +05:30
[merge request template ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md ).
2019-12-21 20:55:43 +05:30
2020-05-24 23:13:21 +05:30
## Other ways to help
2019-12-21 20:55:43 +05:30
If you have ideas for further documentation resources please
2020-06-23 00:09:42 +05:30
[create an issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation )
2019-12-21 20:55:43 +05:30
using the Documentation template.
2020-01-01 13:55:28 +05:30
## Post-merge reviews
If not assigned to a Technical Writer for review prior to merging, a review must be scheduled
immediately after merge by the developer or maintainer. For this,
2020-06-23 00:09:42 +05:30
create an issue using the [Doc Review description template ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review )
2020-01-01 13:55:28 +05:30
and link to it from the merged merge request that introduced the documentation change.
2022-01-26 12:08:38 +05:30
Circumstances in which a regular pre-merge Technical Writer review might be skipped include:
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
- There is a short amount of time left before the milestone release. If fewer than three
2021-11-18 22:05:49 +05:30
days are remaining, seek a post-merge review and ping the writer via Slack to ensure the review is
2020-01-01 13:55:28 +05:30
completed as soon as possible.
- The size of the change is small and you have a high degree of confidence
that early users of the feature (for example, GitLab.com users) can easily
use the documentation as written.
Remember:
- At GitLab, we treat documentation like code. As with code, documentation must be reviewed to
ensure quality.
- Documentation forms part of the GitLab [definition of done ](../contributing/merge_request_workflow.md#definition-of-done ).
- That pre-merge Technical Writer reviews should be most common when the code is complete well in
advance of a milestone release and for larger documentation changes.
- You can request a post-merge Technical Writer review of documentation if it's important to get the
code with which it ships merged as soon as possible. In this case, the author of the original MR
2021-02-22 17:27:13 +05:30
can address the feedback provided by the Technical Writer in a follow-up MR.
2020-01-01 13:55:28 +05:30
- The Technical Writer can also help decide that documentation can be merged without Technical
writer review, with the review to occur soon after merge.
### Before merging
Ensure the following if skipping an initial Technical Writer review:
2021-11-18 22:05:49 +05:30
- [Product badges ](styleguide/index.md#product-tier-badges ) are applied.
2022-07-16 23:28:13 +05:30
- The GitLab [version ](versions.md ) that
2021-11-18 22:05:49 +05:30
introduced the feature is included.
- Changes to headings don't affect in-app hyperlinks.
2020-01-01 13:55:28 +05:30
- Specific [user permissions ](../../user/permissions.md ) are documented.
2021-11-18 22:05:49 +05:30
- New documents are linked from higher-level indexes, for discoverability.
- The style guide is followed:
2022-04-04 11:22:00 +05:30
- For [directories and files ](site_architecture/folder_structure.md ).
2021-01-29 00:20:46 +05:30
- For [images ](styleguide/index.md#images ).
2020-01-01 13:55:28 +05:30
Merge requests that change the location of documentation must always be reviewed by a Technical
2021-11-18 22:05:49 +05:30
Writer before merging.
