kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/development/documentation/improvement-workflow.md

64 lines
4.4 KiB
Markdown
Raw Normal View History

Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
---
description: How to improve GitLab's documentation.
---
Minor fixes to development/documentation docs, mostly aligning all link text to relevant page names
2019-02-21 11:56:24 -05:00
# Documentation improvement workflow
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Anyone can contribute a merge request or create an issue for GitLab's documentation.
Fixed a typo
2018-12-31 09:36:20 -05:00
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
Minor fixes to development/documentation docs, mostly aligning all link text to relevant page names
2019-02-21 11:56:24 -05:00
or feature enhancement, see the [documentation process for feature changes](feature-change-workflow.md).
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Update improvement-workflow, remove Support-specific items
2018-12-27 15:18:26 -05:00
## Who updates the docs
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Update improvement-workflow, remove Support-specific items
2018-12-27 15:18:26 -05:00
Anyone can contribute! You can create a merge request with documentation
Fixed a typo
2018-12-31 09:36:20 -05:00
when you find errors or other room for improvement in an existing doc, or when you
Update improvement workflow
2019-01-17 18:07:01 -05:00
have an idea for all-new documentation that would help a GitLab user or administrator
to accomplish their work with GitLab.
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Updates to doc improvements workflow
2018-12-27 16:59:22 -05:00
## How to update the docs
Update improvement workflow
2019-01-17 18:07:01 -05:00
1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to
Ensure all lists are surrounded by new lines Markdown renderers find it easier to determine where lists start and end when lists are surrounded by new lines. For consistency, also ensure entries in the list are aligned when they span multipls lines.
2019-02-22 08:17:10 -05:00
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.
Update improvement workflow
2019-01-17 18:07:01 -05:00
1. Follow the described standards and processes listed on that Guidelines page,
Ensure all lists are surrounded by new lines Markdown renderers find it easier to determine where lists start and end when lists are surrounded by new lines. For consistency, also ensure entries in the list are aligned when they span multipls lines.
2019-02-22 08:17:10 -05:00
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/).
Update improvement workflow
2019-01-17 18:07:01 -05:00
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
Add to the 'how to update' section
2018-12-31 15:35:24 -05:00
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.
Updates to doc improvements workflow
2018-12-27 16:59:22 -05:00
Update improvement workflow
2019-01-17 18:07:01 -05:00
## Review and merging
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Update improvement-workflow, remove Support-specific items
2018-12-27 15:18:26 -05:00
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).
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Update improvement-workflow, remove Support-specific items
2018-12-27 15:18:26 -05:00
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).
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Update improvement workflow
2019-01-17 18:07:01 -05:00
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.
Update improvement workflow
2019-01-23 00:53:14 -05:00
**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.
Ensure all lists are surrounded by new lines Markdown renderers find it easier to determine where lists start and end when lists are surrounded by new lines. For consistency, also ensure entries in the list are aligned when they span multipls lines.
2019-02-22 08:17:10 -05:00
Update improvement workflow
2019-01-23 00:53:14 -05:00
**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).
Update improvement-workflow re who creates and confirms tech writer review issues
2019-02-18 16:10:26 -05:00
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.
Update improvement workflow
2019-01-17 18:07:01 -05:00
**3. Maintainer**
Updates to doc improvements workflow
2018-12-27 16:59:22 -05:00
Update improvement workflow
2019-01-17 18:07:01 -05:00
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.
Update improvement-workflow re who creates and confirms tech writer review issues
2019-02-18 16:10:26 -05:00
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.
Updates to doc improvements workflow
2018-12-27 16:59:22 -05:00
Update improvement-workflow, remove Support-specific items
2018-12-27 15:18:26 -05:00
## Other ways to help
Updates per reviews; split workflow.md into 2 pages Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
2018-12-21 18:56:21 -05:00
Add line breaks to improvement workflow
2018-12-21 22:56:10 -05:00
If you have ideas for further documentation resources that would be best
Update improvement workflow
2019-01-17 18:07:01 -05:00
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.
Copy permalink