description:How to add docs for new or enhanced GitLab features.
redirect_to:'workflow.md'
---
# Documentation process for feature changes
At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
-**Developers**: Author/update documentation in the same MR as their code, and
merge it in the assigned milestone. Request technical writer
assistance if needed. Other developers typically act as reviewers.
-**Product Managers** (PMs): In the issue for all new and enhanced features,
confirm the documentation requirements, plus the mentioned feature description
and use cases, which can be reused in docs. They can bring in a technical
writer for discussion or collaboration, and can be called upon themselves as a doc reviewer.
-**Technical Writers**: Review doc requirements in issues, track issues and MRs
that contain docs changes, help with any questions throughout the authoring/editing process,
work on special projects related to the documentation, and review all new and updated
docs content, whether before or after it is merged.
Beyond this process, any member of the GitLab community can also author or request documentation
improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md).
## When documentation is required
Documentation must be delivered whenever:
- A new or enhanced feature is shipped that impacts the user/admin experience.
- There are changes to the UI or API.
- A process, workflow, or previously documented feature is changed.
- A feature is deprecated or removed.
For example, a UI restyling that offers no difference in functionality may require
documentation updates if screenshots are now needed, or need to be updated.
Documentation is not required when a feature is changed on the backend
only and does not directly affect the way that any user or administrator would
interact with GitLab.
NOTE: **Note:**
When revamping documentation, if unrelated to the feature change, this should be submitted
in its own MR (using the [documentation improvement workflow](improvement-workflow.md))
so that we can ensure the more time-sensitive doc updates are merged sooner.
## Documentation requirements in feature issues
Requirements for the documentation of a feature should be included as part of the
issue for planning that feature, in a Documentation section within the issue description.
This section is provided as part of the Feature Proposal template and should be added
to the issue if it is not already present.
Anyone can add these details, but the product manager who assigns the issue to a specific release
milestone will ensure these details are present and finalized by the time of that milestone's kickoff.
Developers, technical writers, and others may help further refine this plan at any time.
### Details to include
- What concepts and procedures should the docs guide and enable the user to understand or accomplish?
- To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions.
- For any guide or instruction set, should it help address a single use case, or be flexible to address a certain range of use cases?
- Do we need to update a previously recommended workflow? Should we link the new feature from various relevant locations? Consider all ways documentation should be affected.
- Are there any key terms or task descriptions that should be included so that the docs are found in relevant searches?
- Include suggested titles of any pages or subsections, if applicable.
## Documenting a new or changed feature
To follow a consistent workflow every month, documentation changes
involve the Product Managers, the developer who shipped the feature,
and the technical writer for the DevOps stage. Each role is described below.
The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab/raw/master/.gitlab/issue_templates/Feature%20proposal.md)
and default merge request template will assist you with following this process.
### Product Manager role
For issues requiring any new or updated documentation, the Product Manager (PM)
must:
- Add the ~documentation label.
- Confirm or add the [documentation requirements](#documentation-requirements-in-feature-issues).
- Ensure the issue contains any new or updated feature name, overview/description,
and use cases, as required per the [documentation structure and template](structure.md), when applicable.
Everyone is encouraged to draft the requirements in the issue, but a product manager will
do the following:
- When the issue is assigned a release milestone, review and update the Documentation details.
- By the kickoff, finalize the Documentation details.
### Developer and maintainer roles
#### Authoring
As a developer, if a ~feature issue also contains the ~documentation label, you must ship the new or updated documentation with the code of the feature. The documentation is an essential part of the product.
Technical writers are happy to help, as requested and planned on an issue-by-issue basis.
For feature issues requiring documentation, follow the process below unless otherwise agreed with the product manager and technical writer for a given issue:
- Include any new and edited docs in the MR introducing the code.
- Use the Documentation requirements confirmed by the Product Manager in the
issue and discuss any further doc plans or ideas as needed.
- If the new or changed doc requires extensive collaboration or conversation, a separate,
linked issue can be used for the planning process.
- We are trying to avoid using a separate MR, so that the docs stay with the code, but the
Technical Writing team is interested in discussing any potential exceptions that may be suggested.
- Use the [Documentation guidelines](index.md), as well as other resources linked from there,
including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
- If you need any help to choose the correct place for a doc, discuss a documentation
idea or outline, or request any other help, ping the Technical Writer for the relevant
in your issue or MR, or write within `#docs` on the GitLab Slack.
- If you are working on documentation in a separate MR, ensure that if the code is merged by the 17th, the docs are as well, per the [Engineering Workflow](https://about.gitlab.com/handbook/engineering/workflow/). If the docs are not ready, the PM can approve merging the code if the engineer and tech writer commit to get documentation merged by the 21st. Otherwise the feature is not considered complete, and should not be merged.
- A policy for documenting feature-flagged
issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/56813).
#### Reviews and merging
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the plans in the issue, as well as the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md).
-**Prior to merging**, documentation changes committed by the developer must be reviewed by:
1.**The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
1. Optionally: Others involved in the work, such as other devs or the PM.
1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge.
This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed.
- To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change,
and your degree of confidence in having users of an RC use your docs as written.
- Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes.
- You can request a review and if there is not sufficient time to complete it prior to the freeze,
the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue.
- The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR.
-**To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
-**To request a post-merge technical writer 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.
1.**The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
- Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review), link it from the MR, and
mention the original MR author in the new issue. Alternatively, the maintainer can ask the MR author to create and link this issue before the MR is merged.
- After merging, documentation changes are reviewed by:
1. The technical writer -- **if** their review was not performed prior to the merge.
1. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.
### Technical Writer role
#### Planning
- The technical writer monitors the documentation needs of issues assigned to the current and next milestone
for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement
with the dev, PM, and others.
- The technical writer will review these requirements again upon the kickoff and provide feedback, as needed.
This is not a blocking review and developers should not wait to work on docs.
#### Collaboration
By default, the developer will work on documentation changes independently, but
the developer, PM, or technical writer can propose a broader collaboration for
any given issue.
Additionally, technical writers are available for questions at any time.
#### Review
- Technical writers provide non-blocking reviews of all documentation changes,
before or after the change is merged. However, if the docs are ready in the MR while
there's time before the freeze, the technical writer's review can commence early, on request.
- The technical writer will confirm that the doc is clear, grammatically correct,
and discoverable, while avoiding redundancy, bad file locations, typos, broken links,
etc. The technical writer will review the documentation for the following, which
the developer and code reviewer should have already made a good-faith effort to ensure:
- Clarity.
- Adherence to the plans and goals in the issue.
- Location (make sure the docs are in the correct directories and has the correct name).
- Syntax, typos, and broken links.
- Improvements to the content.
- Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc.
This document was moved to [another location](workflow.md).
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."
description:Learn the processes for contributing to GitLab's documentation.
---
# Documentation process
# Documentation workflows
The process for creating and maintaining GitLab product documentation depends on whether the
documentation is associated with:
Documentation workflows at GitLab differ depending on the reason for the change:
-[A new feature or feature enhancement](#for-a-product-change).
-[Documentation process for feature changes](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
-[Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time.
Delivered for a specific milestone and associated with specific code changes. This documentation
has the highest priority.
-[Changes outside a specific milestone](#for-all-other-documentation).
It is usually not associated with a specific code change and has a lower priority.
Documentation is not usually required when a "backstage feature" is added or changed, and does not
directly affect the way that any user or administrator interacts with GitLab.
## For a product change
This documentation is required for any new or changed feature and is:
- Created or updated as part of feature development, typically via the same merge request as the
feature code.
- Required with the delivery of a feature for a specific milestone as part of GitLab's
[definition of done](../contributing/merge_request_workflow.md#definition-of-done).
- Often linked from the release post.
### Roles and responsibilities
Documentation for specific milestones involves the:
- Developer of a feature or enhancement.
- Product Manager for the group delivering the new feature or feature enhancement.
- Technical Writer assigned to the group.
Each role is described below.
#### Developers
Developers are the primary author of documentation for a feature or feature enhancement. They are
responsible for:
- Developing initial content required for a feature.
- Liaising with their Product Manager to understand what documentation must be delivered, and when.
- Requesting technical reviews from other developers within their group.
- Requesting documentation reviews from the Technical Writer
[assigned to the DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments)
that is delivering the new feature or feature enhancements.
TIP: **Tip:**
Community Contributors can ask for additional help from GitLab team members.
##### Authoring
Because the documentation is an essential part of the product, if a ~feature issue also contains the
~documentation label, you must ship the new or updated documentation with the code of the feature.
Technical Writers are happy to help, as requested and planned on an issue-by-issue basis.
For feature issues requiring documentation, follow the process below unless otherwise agreed with
the Product Manager and Technical Writer for a given issue:
- Include any new and edited documentation, either in:
- The merge request introducing the code.
- A separate merge request raised around the same time.
- Use the [documentation requirements](#documentation-requirements) developed by the Product Manager
in the issue and discuss any further documentation plans or ideas as needed.
If the new or changed documentation requires extensive collaboration or conversation, a
separate, linked issue can be used for the planning process.
- Use the [Documentation guidelines](index.md), as well as other resources linked from there,
including:
- Documentation [Structure and template](structure.md) page.
- Post-merge review, [create an issue for one](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Doc%20Review)
and link it from the MR that makes the documentation change.
- 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
[create the required issue](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Doc%20Review), assign to the technical writer of the given stage group,
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.
