feature-change-workflow.md 10.7 KB
Newer Older
1 2 3 4
---
description: How to add docs for new or enhanced GitLab features.
---

5
# Documentation process for feature changes
6

7
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.
8

9 10
- **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
11
assistance if needed. Other developers typically act as reviewers.
12 13 14
- **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
15
writer for discussion or collaboration, and can be called upon themselves as a doc reviewer.
16
- **Technical Writers**: Review doc requirements in issues, track issues and MRs
17
that contain docs changes, help with any questions throughout the authoring/editing process,
18 19
work on special projects related to the documentation, and review all new and updated
docs content after it's merged (unless a pre-merge review request is made).
20

21
Beyond this process, any member of the GitLab community can also author or request documentation
22
improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md).
23 24

## When documentation is required
25 26 27

Documentation must be delivered whenever:

28 29 30 31
- 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.
32 33

Documentation is not required when a feature is changed on the backend
34 35 36 37
only and does not directly affect the way that any user or
administrator would interact with GitLab. 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.
38 39

NOTE: **Note:**
40
When revamping documentation, if unrelated to the feature change, this should be submitted
41 42
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.
43

44
## Documentation requirements in feature issues
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64

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.

65
## Documenting a new or changed feature
66 67 68

To follow a consistent workflow every month, documentation changes
involve the Product Managers, the developer who shipped the feature,
69
and the technical writer for the DevOps stage. Each role is described below.
70

71
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)
72
and default merge request template will assist you with following this process.
73

74
### 1. Product Manager's role
75

76 77 78 79 80 81 82
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).
- 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.
83

84 85
Everyone is encouraged to draft the requirements in the issue, but a product manager will
do the following:
86

87 88
- When the issue is assigned a release milestone, review and update the Documentation details.
- By the kickoff, finalizie the Documentation details.
89

90
### 2. Developer and maintainer roles
91

92
#### Authoring
93

94 95
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.
96
Technical writers are happy to help, as requested and planned on an issue-by-issue basis.
97

98 99 100 101
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
102
issue and discuss any further doc plans or ideas as needed.
103 104 105
   - 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
106
Technical Writing team is interested in discussing any potential exceptions that may be suggested.
107
- Use the [Documentation guidelines](index.md), as well as other resources linked from there,
108
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/). 
109
- If you need any help to choose the correct place for a doc, discuss a documentation
110
idea or outline, or request any other help, ping the Technical Writer for the relevant
111 112
[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
in your issue or MR, or write within `#docs` on the GitLab Slack.
113
- The docs must be merged with the code **by the feature freeze date**, otherwise
114 115
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).
116

117
#### Reviews and merging
118 119 120

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).

121
- Prior to merge, documentation changes committed by the developer must be reviewed by:
122

123 124 125 126 127 128 129 130 131 132 133
   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.
   1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability.
134

135 136
- Upon merging, if a technical writer review has not been performed, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review)
if one was not already created by the developer or reviewer.
137

138
- After merging, documentation changes are reviewed by:
139 140 141

   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).
142
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.
143

144 145
### 3. Technical Writer's role

146 147
#### Planning

148 149
- 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
150
with the dev, PM, and others.
151 152
- The technical writer will review these again upon the kickoff and provide feedback, as needed.
This is not a blocking review and developers should not wait to work on docs.
153

154 155 156 157 158 159 160 161 162 163
#### 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.

#### Review

164
- Techncial writers provide non-blocking reviews of all documentation changes,
165
before or after the change is merged. However, if the docs are ready in the MR while
166
there's time before the freeze, the technical writer's review can commence early, on request.
167 168 169 170
- 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:
171
  - Clarity.
172 173
  - Adherence to the plans and goals in the issue.
  - Location (make sure the docs are in the correct directorkes and has the correct name).
174 175
  - Syntax, typos, and broken links.
  - Improvements to the content.
176
  - Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc.