kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Update improvement workflow

Browse source
This commit is contained in:
Mike Lewis 2019-01-17 23:07:01 +00:00
parent 77f3cbc008
commit 75cf4bdf93
1 changed files with 29 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
doc/development/documentation/improvement-workflow.md
View file

@ -2,7 +2,7 @@
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.
@ -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
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
to achieve or improve their DevOps workflows.
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
- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page,
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/).
- Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
- If you need any help to choose the correct place for a doc, discuss a documentation
1. Click "Edit this Page" at the bottom of any page on 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/).
1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
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
[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
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.
This person must make a good-faith effort to ensure that the content is clear
@ -38,12 +42,25 @@ 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
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.
The technical writing team reviews changes after they are merged, unless a prior
review is requested.
**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: Technical writer review. 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).
**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.
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, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review).
## 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.
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)
using the Documentation template.