description:How to improve GitLab's documentation.
redirect_to:'workflow.md'
---
# Documentation improvement workflow
Anyone can contribute a merge request or create an issue for GitLab's documentation.
This page covers the process for any contributions to GitLab's docs that are
not part of feature development. If you are looking for information on updating
GitLab's docs as is required with the development and release of a new feature
or feature enhancement, see the [documentation process for feature changes](feature-change-workflow.md).
## Who updates the docs
Anyone can contribute! You can create a merge request with documentation
when you find errors or other room for improvement in an existing doc, or when you
have an idea for all-new documentation that would help a GitLab user or administrator
to accomplish their work with GitLab.
## How to update the docs
1. Click "Edit this Page" at the bottom of any page on <https://docs.gitlab.com>, or navigate to
one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page.
Work in a fork if you do not have developer access to the GitLab project.
1. Follow the described standards and processes listed on that Guidelines page,
including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace.
## Review and merging
Anyone with master access to the affected GitLab project can merge documentation changes.
This person must make a good-faith effort to ensure that the content is clear
(sufficiently easy for the intended audience to navigate and understand) and
that it meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md).
If the author or reviewer has any questions, or would like a technical writer's review
before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
The process can involve the following parties/phases, and is replicated in the `Documentation` MR template for GitLab CE and EE, to help with following the process.
**1. 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.
**2. Technical Writer** - Optional - If not requested for this MR, must be scheduled post-merge. To request a pre-merge review, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
To request a post-merge review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
**3. Maintainer**
1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review.
1. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone.
1. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
1. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review) and link it from the MR.
## Other ways to help
If you have ideas for further documentation resources that would be best
considered/handled by technical writers, devs, and other SMEs, please [create an issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Documentation)
using the Documentation template.
This document was moved to [another location](workflow.md).
@@ -212,9 +212,9 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
- Use inclusive language and avoid jargon, as well as uncommon
words. The docs should be clear and easy to understand.
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
- Write in the 3rd person (use "we," "you," "us," "one," instead of "I" or "me").
- Be clear, concise, and stick to the goal of the doc.
- Write in US English.
- Write in US English with US grammar.
- Capitalize "G" and "L" in GitLab.
- Use title case when referring to:
-[GitLab Features](https://about.gitlab.com/features/). For example, Issue Board,
...
...
@@ -225,9 +225,23 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
- Methods or methodologies. For example, Continuous Integration, Continuous
Deployment, Scrum, and Agile.
NOTE: **Note:**
Some features are also objects. For example, "GitLab's Merge Requests support X." and
"Create a new merge request for Z.".
NOTE: **Note:**
Some features are also objects. For example, "GitLab's Merge Requests support X" and
"Create a new merge request for Z."
- Avoid use of the future tense:
- Instead of, "After you execute this command, the result will be displayed," say "After you execute this command, the result is displayed."
- Only use the future tense to convey when the action or result will actually occur at a future time.
- Do not use contractions:
- Instead of "don't," "can't," "doesn't," and so on, say "do not," "cannot," or "does not."
- Possible exceptions are cases when a more familiar tone is desired, such as a blog post or other casual context.
- Do not use slashes to clump different words together or as a replacement for the word "or":
- Instead of "and/or," consider saying "or," or use another sensible construction.
- Other examples include "clone/fetch," author/assignee," and "namespace/repository name." Break apart any such instances in an appropriate way.
- Exceptions to this rule include commonly accepted technical terms such as CI/CD, TCP/IP, and so on.
- Do not use "may" and "might" interchangeably:
- Use "might" to indicate the probability of something occurring. "If you skip this step, the import process might fail."
- Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen."
the [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager)
chart was used.
NOTE: **Note:**
If you have installed cert-manager prior to GitLab 12.3, Let's Encrypt will
[block requests from older versions of cert-manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753).
To resolve this, uninstall cert-manager (consider [backing up any additional configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html)), then install cert-manager again.
### GitLab Runner
> - Introduced in GitLab 10.6 for project-level clusters.
