- [ ] Follow-up from: #XXX, !YYY <!-- Mention related issues, MRs, and epics when available -->
## New doc or update?
<!-- Un-comment the line for the applicable doc issue type to add its label.
Note that all text on that line is deleted upon issue creation. -->
<!-- /label ~"docs:fix" - Correction or clarification needed. -->
<!-- /label ~"docs:new" - New doc needed to cover a new topic or use case. -->
<!-- /label ~"docs:improvement" - Improving an existing doc; e.g. adding a diagram, adding or rewording text, resolving redundancies, cross-linking, etc. -->
<!-- /label ~"docs:revamp" - Review a page or group of pages in order to plan and implement major improvements/rewrites. -->
<!-- /label ~"docs:other" - Anything else. -->
<!-- Mark either of these boxes: -->
### Problem to solve
- [ ] New documentation
<!-- Include the following detail as necessary:
- [ ] Update existing documentation
* What product or feature(s) affected?
* What docs or doc section affected? Include links or paths.
* Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs?
* Any other ideas or requests?
-->
## Checklists
### Further details
### Product Manager
<!--
* Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab?
* Include use cases, benefits, and/or goals for this work.
* If adding content: What audience is it intended for? (What roles and scenarios?)
For ideas, see personas at https://design.gitlab.com/research/personas or the persona labels at
@@ -31,15 +31,20 @@ Existing personas are: (copy relevant personas out of this comment, and delete a
...
@@ -31,15 +31,20 @@ Existing personas are: (copy relevant personas out of this comment, and delete a
### Further details
### Further details
<!--- Include use cases, benefits, and/or goals (contributes to our vision?) -->
<!-- Include use cases, benefits, and/or goals (contributes to our vision?) -->
### Proposal
### Proposal
<!--- How are we going to solve the problem? Try to include the user journey! -->
<!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey -->
### Documentation
<!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html
Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements -->
### What does success look like, and how can we measure that?
### What does success look like, and how can we measure that?
<!--- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this -->
<!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. -->
<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation -->
<!-- Follow the documentation workflow https://docs.gitlab.com/ee/development/documentation/workflow.html -->
<!-- Additional information is located at https://docs.gitlab.com/ee/development/documentation/ -->
<!-- Mention "documentation" or "docs" in the MR title -->
<!-- Mention "documentation" or "docs" in the MR title -->
<!-- For changing documentation location use the "Change documentation location" template -->
<!-- Use this description template for new docs or updates to existing docs. For changing documentation location use the "Change documentation location" template -->
## What does this MR do?
## What does this MR do?
<!-- Briefly describe what this MR is about -->
<!-- Briefly describe what this MR is about. -->
## Related issues
## Related issues
<!-- Mention the issue(s) this MR closes or is related to -->
<!-- Link related issues below. Insert the issue link or reference after the word "Closes" if merging this should automatically close it. -->
Closes
## Author's checklist
## Author's checklist
-[ ] [Apply the correct labels and milestone](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#1-product-managers-role)
-[ ] Follow the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
- [ ] Crosslink the document from the higher-level index
- [ ] Link docs to and from the higher-level index page, plus other related docs where helpful.
- [ ] Crosslink the document from other subject-related docs
- [ ] Apply the ~Documentation label.
-[ ] Feature moving tiers? Make sure the change is also reflected in [`features.yml`](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml)
-[ ] Correctly apply the product [badges](https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges) and [tiers](https://docs.gitlab.com/ee/development/documentation/styleguide.html#gitlab-versions-and-tiers)
-[ ] [Port the MR to EE (or backport from CE)](https://docs.gitlab.com/ee/development/documentation/index.html#cherry-picking-from-ce-to-ee): _always recommended, required when the `ee-compat-check` job fails_
## Review checklist
## Review checklist
- [ ] Your team's review (required)
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
- [ ] PM's review (recommended, but not a blocker)
- [ ] Technical writer's review (required)
**1. Primary Reviewer**
- [ ] Merge the EE-MR first, CE-MR afterwards
* [ ] Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.
**2. Technical Writer**
*[ ] Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
**3. Maintainer**
1. [ ] Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
1. [ ] Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist.
1.[ ] If there has not been a technical writer review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review).
and [structure](https://docs.gitlab.com/ee/development/documentation/structure.html).
and [structure](https://docs.gitlab.com/ee/development/documentation/structure.html) guides.
Note that a technical writer will review all changes to documentation. This can occur
in the same MR as the feature code, but [if there is not sufficient time or need,
it can be planned via a follow-up issue for doc review](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#1-product-managers-role),
and another MR, if needed. Regardless, complete docs must be merged with code by the freeze.
#### What happens if these deadlines are missed?
#### What happens if these deadlines are missed?
...
@@ -206,8 +210,6 @@ and to prevent any last minute surprises.
...
@@ -206,8 +210,6 @@ and to prevent any last minute surprises.
Merge requests should still be complete, following the [definition of done][done].
Merge requests should still be complete, following the [definition of done][done].
#### Feature merge requests
If a merge request is not ready, but the developers and Product Manager
If a merge request is not ready, but the developers and Product Manager
responsible for the feature think it is essential that it is in the release,
responsible for the feature think it is essential that it is in the release,
they can [ask for an exception](#asking-for-an-exception) in advance. This is
they can [ask for an exception](#asking-for-an-exception) in advance. This is
...
@@ -222,34 +224,17 @@ information, see
...
@@ -222,34 +224,17 @@ information, see
[Automatic CE->EE merge][automatic_ce_ee_merge] and
[Automatic CE->EE merge][automatic_ce_ee_merge] and
[Guidelines for implementing Enterprise Edition features][ee_features].
[Guidelines for implementing Enterprise Edition features][ee_features].
#### Documentation merge requests
Documentation is part of the product and must be shipped with the feature.
The single exception for the feature freeze is documentation, and it can
be left to be **merged up to the 14th** if:
* There is a follow-up issue to add documentation.
* It is assigned to the developer writing documentation for this feature, and they
are aware of it.
* It is in the correct milestone, with the labels ~Documentation, ~Deliverable,
~missed-deliverable, and "pick into X.Y" applied.
* It must be reviewed and approved by a technical writer.
Once the stable branch is frozen, the only MRs that can be cherry-picked into
Once the stable branch is frozen, the only MRs that can be cherry-picked into
the stable branch are:
the stable branch are:
* Fixes for [regressions](#regressions) where the affected version `xx.x` in `regression:xx.x` is the current release. See [Managing bugs](#managing-bugs) section.
* Fixes for [regressions](#regressions) where the affected version `xx.x` in `regression:xx.x` is the current release. See [Managing bugs](#managing-bugs) section.
* Fixes for security issues
* Fixes for security issues.
* Fixes or improvements to automated QA scenarios
* Fixes or improvements to automated QA scenarios.
*[Documentation updates](https://docs.gitlab.com/ee/development/documentation/workflow.html#documentation-shipped-late) for changes in the same release
*[Documentation improvements](https://docs.gitlab.com/ee/development/documentation/workflow.html) for feature changes made in the same release, though initial docs for these features should have already been merged by the freeze, as required.
* New or updated translations (as long as they do not touch application code)
* New or updated translations (as long as they do not touch application code).
* Changes that are behind a feature flag and have the ~"feature flag" label
* Changes that are behind a feature flag and have the ~"feature flag" label.
During the feature freeze all merge requests that are meant to go into the
During the feature freeze all merge requests that are meant to go into the
upcoming release should have the correct milestone assigned _and_ the
upcoming release should have the correct milestone assigned _and_ the
{help: s_("Profiles|This email will be used for web based operations, such as edits and merges. %{learn_more}").html_safe%{learn_more: commit_email_docs_link}},
{help: s_("Profiles|This email will be used for web based operations, such as edits and merges. %{learn_more}").html_safe%{learn_more: commit_email_docs_link}},
When your content is ready for review, assign the MR to a technical writer
Per the [documentation workflows](https://docs.gitlab.com/ee/development/documentation/workflow.html), the review may occur prior to merging this MR **or** after a maintainer has agreed to review and merge this MR without a tech writer review. (Meanwhile, you are welcome to involve a technical writer at any time if you have questions about writing or updating the documentation. GitLabbers are also welcome to use the [#docs](https://gitlab.slack.com/archives/C16HYA2P5) channel on Slack.)
according to the [DevOps stages](https://about.gitlab.com/handbook/product/categories/#devops-stages)
in the table below. If necessary, mention them in a comment explaining what needs
The technical writer who, by default, will review this content or collaborate as needed is dependent on the [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) to which the content applies:
You are welcome to mention them sooner if you have questions about writing or
**To request a review prior to merging**
updating the documentation. GitLabbers are also welcome to use the
[#docs](https://gitlab.slack.com/archives/C16HYA2P5) channel on Slack.
- Assign the MR to the applicable technical writer, above. If you are not sure which category the change falls within, or the change is not part of one of these categories, mention one of the usernames above.
**To request a review to commence after merging**
If you are not sure which category the change falls within, or the change is not
- Create an issue for a doc review [using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and assign it to the applicable technicial writer from the table.
part of one of these categories, mention one of the usernames above.
description:How to add docs for new or enhanced GitLab features.
description:How to add docs for new or enhanced GitLab features.
---
---
# Documentation process at GitLab
# 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.
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
-**Developers**: Author/update documentation in the same MR as their code, and
merge it by the feature freeze for the assigned milestone. Request technical writer
merge it by the feature freeze for the assigned milestone. Request technical writer
assistance if needed.
assistance if needed. Other developers typically act as reviewers.
-**Product Managers** (PMs): In the issue for all new and enhanced features,
-**Product Managers** (PMs): In the issue for all new and enhanced features,
confirm the documentation requirements, plus the mentioned feature description
confirm the documentation requirements, plus the mentioned feature description
and use cases, which can be reused in docs. They can bring in a technical
and use cases, which can be reused in docs. They can bring in a technical
writer for discussion or help, and can be called upon themselves as a doc reviewer.
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
-**Technical Writers**: Review doc requirements in issues, track issues and MRs
that contain docs changes, help with any questions throughout the authoring/editing process,
that contain docs changes, help with any questions throughout the authoring/editing process,
and review all new and updated docs content after it's merged (unless a pre-merge
work on special projects related to the documentation, and review all new and updated
review request is made).
docs content, whether before or after it is merged.
Beyond this process, any member of the GitLab community can also author documentation
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).
improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md).
## When documentation is required
## When documentation is required
Documentation must be delivered whenever:
Documentation must be delivered whenever:
- A new or enhanced feature is shipped that impacts the user/admin experience
- A new or enhanced feature is shipped that impacts the user/admin experience.
- There are changes to the UI or API
- There are changes to the UI or API.
- A process, workflow, or previously documented feature is changed
- A process, workflow, or previously documented feature is changed.
- A feature is deprecated or removed
- 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
Documentation is not required when a feature is changed on the backend
only and does not directly affect the way that any user or
only and does not directly affect the way that any user or administrator would
administrator would interact with GitLab. For example, a UI restyling that offers
interact with GitLab.
no difference in functionality may require documentation updates if screenshots
are now needed, or need to be updated.
NOTE: **Note:**
NOTE: **Note:**
When revamping documentation, if unrelated to the feature change, this should be submitted
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))
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 with code by the freeze.
so that we can ensure the more time-sensitive doc updates are merged with code by the freeze.
## 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
## Documenting a new or changed feature
To follow a consistent workflow every month, documentation changes
To follow a consistent workflow every month, documentation changes
involve the Product Managers, the developer who shipped the feature,
involve the Product Managers, the developer who shipped the feature,
and the Technical Writing team. Each role is described below.
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-ce/raw/template-improvements-for-documentation/.gitlab/issue_templates/Feature%20proposal.md)
and default merge request template will assist you with following this process.
### Product Manager role
### 1. Product Manager's role
For issues requiring any new or updated documentation, the Product Manager (PM)
must:
The Product Manager (PM) should confirm or add the following items in the issue:
- Add the `Documentation` label.
- Confirm or add the [documentation requirements](#documentation-requirements).
- 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.
- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md).
Everyone is encouraged to draft the requirements in the issue, but a product manager will
- The documentation requirements for the developer working on the docs.
do the following:
- What new page, new subsection of an existing page, or other update to an existing page/subsection is needed.
- Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected.
- Suggested title of any page or subsection, if applicable.
- Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone.
Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone.
- When the issue is assigned a release milestone, review and update the Documentation details.
- By the kickoff, finalizie the Documentation details.
### 2. Developer's role
### Developer and maintainer roles
#### Authoring
As a developer, you must ship the documentation with the code of the feature that
As a developer, you must ship the documentation with the code of the feature that
you are creating or updating. The documentation is an essential part of the product.
you are creating or updating. 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.
Follow the process below unless otherwise agreed with the product manager and technical writer for a given issue:
- New and edited docs should be included in the MR introducing the code, and planned
- Include any new and edited docs in the MR introducing the code.
in the issue that proposed the feature. However, if the new or changed doc requires
- Use the Documentation requirements confirmed by the Product Manager in the
extensive collaboration or conversation, a separate, linked issue can be used for the planning process.
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,
- Use the [Documentation guidelines](index.md), as well as other resources linked from there,
including the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
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
- 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
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.
in your issue or MR, or write within `#docs` on the GitLab Slack.
- The docs must be merged with the code **by the feature freeze date**, otherwise
- The docs must be merged with the code **by the feature freeze date**, otherwise
- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues -->
the feature cannot be included with the release. A policy for documenting feature-flagged
issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813).
Prior to merge, documentation changes commited by the developer must be reviewed by:
#### Reviews and merging
* the person reviewing the code and merging the MR.
* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested.
After merging, documentation changing are reviewed by:
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the plans in the issue, as well as the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
* a technical writer (for clarity, structure, grammar, etc).
* optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
-**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-ce/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-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and
mention the original MR author in the new issue. Alternatively, the mainitainer 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.
2. 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.
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.
### 3. Technical Writer's role
### 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 technicial writer can propose a broader collaboration for
any given issue.
Additionally, technical writers are available for questions at any time.
**Planning**
#### Review
- Once an issue contains a Documentation label and an upcoming milestone, a
technical writer reviews the listed documentation requirements, which should have
already been reviewed by the PM. (These are non-blocking reviews; developers should
not wait to work on docs.)
- Monitor the documentation needs of issues assigned to the current and next milestone,
and participate in any needed discussion on docs planning with the dev, PM, and others.
**Review**
- Techncial writers provide non-blocking reviews of all documentation changes,
- Techncial writers provide non-blocking reviews of all documentation changes,
typically after the change is merged. However, if the docs are ready in the MR while
before or after the change is merged. However, if the docs are ready in the MR while
we are awaiting other work in order to merge, the technical writer's review can commence early.
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,
- The technical writer will confirm that the doc is clear, grammatically correct,
and discoverable, while avoiding redundancy, bad file locations, typos, broken links,
and discoverable, while avoiding redundancy, bad file locations, typos, broken links,
etc. The technical writer will review the documentation for the following, which
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:
the developer and code reviewer should have already made a good-faith effort to ensure:
- Clarity.
- Clarity.
-Relevance (make sure the content is appropriate given the impact of the feature).
-Adherence to the plans and goals in the issue.
- Location (make sure the doc is in the correct dir and has the correct name).
- Location (make sure the docs are in the correct directorkes and has the correct name).
- Syntax, typos, and broken links.
- Syntax, typos, and broken links.
- Improvements to the content.
- Improvements to the content.
- Accordance to the [Documentation Style Guide](styleguide.md) and [structure/template](structure.md).
- Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc.
description:How to improve GitLab's documentation.
description:How to improve GitLab's documentation.
---
---
# Documentation improvement workflow
# Documentation Improvement Workflow
Anyone can contribute a merge request or create an issue for GitLab's documentation.
Anyone can contribute a merge request or create an issue for GitLab's documentation.
...
@@ -15,20 +15,24 @@ or feature enhancement, see the [feature-change documentation workflow](feature-
...
@@ -15,20 +15,24 @@ or feature enhancement, see the [feature-change documentation workflow](feature-
Anyone can contribute! You can create a merge request with documentation
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
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 admin
have an idea for all-new documentation that would help a GitLab user or administrator
to achieve or improve their DevOps workflows.
to accomplish their work with GitLab.
## How to update the docs
## How to update the docs
- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page,
1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to
including 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/).
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.
- If you need any help to choose the correct place for a doc, discuss a documentation
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.
in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace.
## Merging
## Review and merging
Anyone with master access to the affected GitLab project can merge documentation changes.
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
This person must make a good-faith effort to ensure that the content is clear
...
@@ -38,12 +42,22 @@ that it meets the [Documentation Guidelines](index.md) and [Style Guide](stylegu
...
@@ -38,12 +42,22 @@ that it meets the [Documentation Guidelines](index.md) and [Style Guide](stylegu
If the author or reviewer has any questions, or would like a techncial writer's review
If the author or reviewer has any questions, or would like a techncial 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).
before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
## Technical Writer review
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-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change.
**3. Maintainer**
The technical writing team reviews changes after they are merged, unless a prior
1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review.
review is requested.
2. 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.
3. If EE and CE MRs exist, merge the EE MR first, then the CE MR.
4. 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-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR.
## Other ways to help
## Other ways to help
If you have ideas for further documentation resources that would be best
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.
considered/handled by technical writers, devs, and other SMEs, please [create an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Documentation)
msgid "Labels|Promoting %{labelTitle} will make it available for all projects inside %{groupName}. Existing project labels with the same title will be merged. This action cannot be reversed."
msgid "Labels|Promoting %{labelTitle} will make it available for all projects inside %{groupName}. Existing project labels with the same title will be merged. This action cannot be reversed."
msgstr ""
msgstr ""
msgid "Language"
msgstr ""
msgid "Large File Storage"
msgid "Large File Storage"
msgstr ""
msgstr ""
...
@@ -7220,6 +7223,9 @@ msgstr ""
...
@@ -7220,6 +7223,9 @@ msgstr ""
msgid "Preferences|Navigation theme"
msgid "Preferences|Navigation theme"
msgstr ""
msgstr ""
msgid "Preferences|This feature is experimental and translations are not complete yet"
msgstr ""
msgid "Press Enter or click to search"
msgid "Press Enter or click to search"
msgstr ""
msgstr ""
...
@@ -7418,9 +7424,6 @@ msgstr ""
...
@@ -7418,9 +7424,6 @@ msgstr ""
msgid "Profiles|This emoji and message will appear on your profile and throughout the interface."
msgid "Profiles|This emoji and message will appear on your profile and throughout the interface."
msgstr ""
msgstr ""
msgid "Profiles|This feature is experimental and translations are not complete yet"
msgstr ""
msgid "Profiles|This information will appear on your profile"
msgid "Profiles|This information will appear on your profile"
