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

Update with additional policy changes discussed with product

This commit is contained in:
Mike Lewis 2018-12-24 18:07:07 +00:00
parent 8fe01378b0
commit 295a02193e
1 changed files with 97 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
doc/development/documentation/feature-change-workflow.md
View File

@ -2,172 +2,159 @@
description: How to add docs for new or enhanced GitLab features. description: How to add docs for new or enhanced GitLab features.
--- ---
# Feature-change documentation updates # Documentation process at GitLab
At GitLab, before each release, 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.
- Product Managers (PMs): in the issue for all new and updated features, - **Product Managers** (PMs): in the issue for all new and updated features,
PMs include specific documentation requirements that the developer who is PMs include specific documentation requirements for the developer, and, for new features,
writing or updating the docs must meet, along with feature descriptions they also include feature descriptions and use cases. They can bring in a technical
and use cases. They call out any specific areas where collaborating with writer for discussion or help, and can be called upon themselves as a doc reviewer.
a technical writer is recommended, and usually act as the first reviewer - **Developers**: author documentation and merge it by the feature freeze, leaving
of the docs. time for a doc review performed by the cross-functional team's assigned technical writer.
- Developers: author documentation and merge it on time (up to a week after - **Technical Writers**: review PM requirements in issues, help developers with any
the feature freeze). questions throughout the authoring/editing process, and review all new and
- Technical Writers: review each issue to ensure PM's requirements are complete, updated docs content before it's merged.
help developers with any questions throughout the process, and act as the final
reviewer of all new and updated docs content before it's merged.
## Requirements Any of the above roles, or others in the GitLab community, can author documentation
improvements that are not associated with a new/changed feature, and must also typically
assign such changes to a technical writer for review.
## When documentation is required
Documentation must be delivered whenever: Documentation must be delivered whenever:
- A new feature is shipped - A new feature is shipped
- There are changes to the UI - 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
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 regular user or only and does not directly affect the way that any user or
administrator would interact with GitLab. administrator would interact with GitLab. For example, a UI restyling that offers
no difference in functionality may require documentation updates if screenshots
Documentation pages should follow the [structure](structure.md) guidelines. are now needed, or need to be updated.
NOTE: **Note:** NOTE: **Note:**
When refactoring documentation, it should be submitted in its own MR. When refactoring documentation, it should be submitted in its own MR.
**Do not** join new features' MRs with refactoring existing docs, as they might have **Do not** join new features' MRs with those refactoring existing docs, as they
different priorities. might have different priorities.
NOTE: **Note:** NOTE: **Note:**
[Smaller MRs are better](https://gitlab.com/gitlab-com/blog-posts/issues/185#note_4401010)! Do not mix subjects, and ship the smallest MR possible. [Smaller MRs are better](https://gitlab.com/gitlab-com/blog-posts/issues/185#note_4401010)! Do not mix subjects (e.g. multiple unrelated pages), and ship the smallest MR possible.
## Review process ## Documenting a new or changed feature
The docs shipped by the developer should be reviewed by the PM (for accuracy) and a Technical Writer (for clarity and structure).
### Documentation updates that require Technical Writer review
Every documentation change that meets the criteria below must be reviewed by a Technical Writer
to ensure clarity and discoverability, and avoid redundancy, bad file locations, typos, broken links, etc.
Within the GitLab issue or MR, ping the relevant technical writer for the subject area. If you're not sure who that is,
ping any of them or all of them (`@gl\-docsteam`).
A Technical Writer must review documentation updates that involve:
- Docs introducing new features
- Changing documentation location
- Refactoring existing documentation
- Creating new documentation files
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 a Technical Writer on your issue, MR,
or on Slack in `#docs`.
### Skip the PM's review
When there's a non-significant change to the docs, you can skip the review
of the PM. Add the same labels as you would for a regular doc change and
assign the correct milestone. In these cases, assign a Technical Writer
for approval/merge, or mention `@gl\-docsteam` in case you don't know
which Tech Writer to assign for.
### Skip the entire review
When the MR only contains corrections to the content (typos, grammar,
broken links, etc), it can be merged without the PM's and tech writer's review.
## Feature documentation workflow
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 Writing team. Each role is described below.
### 1. Product Manager's role in the documentation process ### 1. Product Manager's role
The Product Manager (PM) should add to the feature issue: The Product Manager (PM) should add to the feature issue:
- Feature name, overview/description, and use cases, for the [documentation blurb](structure.md#documentation-blurb) - New or updated feature name, overview/description, and use cases, for the feature's [documentation blurb](structure.md#documentation-blurb)
- The documentation requirements for the developer working on the docs - The documentation requirements for the developer working on the docs
- What new page, new subsection of an existing page, or other update to an existing page/subsection is needed. - 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 - 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 - Suggested title of any page or subsection, if applicable <--!TODO: Add this and previous bullets in some form to issue/MR templates-->
- Label the issue with `Documentation`, `Deliverable`, `docs:P1`, and assign - Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone.
the correct milestone
### 2. Developer's role in the documentation process 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.
### 2. Developer's role
As a developer, or as a community contributor, you should ship the documentation As a developer, or as a community contributor, you should ship the documentation
with the feature, as in GitLab the documentation is part of the product. with the feature; the documentation is an essential part of the product.
The docs can either be shipped along with the MR introducing the code, or, New and edited docs should be shipped along with the MR introducing the code.
alternatively, created from a follow-up issue and MR. However, if the new or changed doc requires extensive collaboration or conversation,
a separate, linked issue and MR can be used.
The docs should be shipped **by the feature freeze date**. Justified For guidance, see the documentation [Structure](structure.md) guide, [Style Guide](styleguide.md), the [main page](index.md) of this section, and additional writing tips in the [Technical Writing handbook section](https://about.gitlab.com/handbook/product/technical-writing/).
exceptions are accepted, as long as the [following process](#documentation-shipped-late) and the missed-deliverable due date (the 14th of each month) are both respected.
### Documentation shipped in the feature MR 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 in `#docs` on the GitLab Slack.
The developer should add to the feature MR the documentation containing: The docs must be shipped **by the feature freeze date**, otherwise the feature cannot be included with the release.
In rare exceptions with the approval of the PM, dev, and technical writer, documentation can be
merged through the 14th of the month if the [following process](#documentation-shipped-late) is followed. <!-- TODO: Policy/process for feature-floagged issues-->
- The [documentation blurb](structure.md#documentation-blurb): copy the Documentation changes commited by the developer should be reviewed by:
feature name, overview/description, and use cases from the feature issue * a technical writer (for clarity, structure, and confirming requirements are met)
* 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 this at the outset.
#### Including documentation in the feature MR (typical)
The developer should add to the feature MR changes to the documentation, typically containing the following for new features:
- The [name, description, and use cases](structure.md#documentation-blurb): copy these from the feature issue
where were provided or reviewed by the product manager.
- Instructions: write how to use the feature, step by step, with no gaps. - Instructions: write how to use the feature, step by step, with no gaps.
- [Crosslink for discoverability](structure.md#discoverability): link with - [Crosslink for discoverability](structure.md#discoverability): link with
internal docs and external resources (if applicable) internal docs and external resources (if applicable).
- Index: link the new doc or the new heading from the higher-level index - Index: link the new doc or the new heading from the higher-level index
for [discoverability](#discoverability) for [discoverability](#discoverability).
- [Screenshots](styleguide.md#images): when necessary, add screenshots for: - [Screenshots](styleguide.md#images): when necessary, add screenshots for:
- Illustrating a step of the process - Illustrating a step of the process.
- Indicating the location of a navigation menu - Indicating the location of a navigation menu.
- Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign - Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign
the correct milestone the correct milestone.
- Assign the PM for review - Assign the PM for review.
- When done, mention the `@gl\-docsteam` in the MR asking for review - When done, mention the team's technical writer in the MR asking for review (or `@gl\-docsteam` if you are not sure who that is).
- **Due date**: feature freeze date and time - **Due date**: feature freeze date and time.
### Documentation shipped in a follow-up MR #### Including documentation in a separate MR
If the docs aren't being shipped within the feature MR: If the docs aren't being shipped within the feature MR, but are still being shipped on time (by the feature freeze):
- Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template) - Create a new issue with the Documentation template and mention "docs" or "documentation" in the title, plus the feature name.
- Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>` - Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>`.
(product label == CI/CD, Pages, Prometheus, etc) (product label == CI/CD, Pages, etc).
- Add the correct milestone - Add the milestone matching that of the feature issue.
- Create a new MR for shipping the docs changes and follow the same - Create a new MR for shipping the docs changes and follow the same
process [described above](#documentation-shipped-in-the-feature-mr) process [described above](#including-documentation-in-the-feautre-mr-typical).
- Use the MR description template called "Documentation" - Use the MR description template named "Documentation".
- Add the same labels and milestone as you did for the issue - Add the same labels and milestone as you did for the issue.
- Assign the PM for review - Assign the technical writer for review.
- When done, mention the `@gl\-docsteam` in the MR asking for review - When done, mention the team's technical writer in the MR asking for review (or `@gl\-docsteam` if you are not sure who that is).
- **Due date**: feature freeze date and time - **Due date**: feature freeze date and time.
### Documentation shipped late #### Shipping documentation after the freeze (rare)
Shipping late means that you are affecting the whole feature workflow Typically, if the documentation is not ready, this will block the feature
as well as other teams' priorities (PMs, tech writers, release managers, for the current GitLab release.
release post reviewers), so every effort should be made to avoid this.
If you did not ship the docs within the feature freeze, proceed as Shipping documentation after the freeze is rare and requires approval of the PM, technical writer, and dev.
[described above](#documentation-shipped-in-a-follow-up-mr) and, Every effort should be made to avoid this, as it risks a poor user experience and affects the whole feature workflow, along with
besides the regular labels, include the labels `Pick into X.Y` and other teams' priorities (PMs, tech writers, release managers, release post reviewers).
`missed-deliverable` in the issue and the MR, and assign them the correct
milestone.
The **due date** for **merging** `missed-deliverable` MRs is on the If the aforementioned approval is given:
**14th** of each month. 1. Use the instructions above for [Documentation shipped in a separate MR](#including-documentation-in-a-separate-mr) and,
in addition to the usual labels and correct milestone, include the labels `Pick into X.Y` on the MR (where X.Y is the GitLab version) and
`missed-deliverable` in the issue and the MR.
2. Obtain a review, as usual.
3. Ensure that the MR is merged by the 14th of the month.
### 3. Technical Writer's role in the documentation process ### 3. Technical Writer's role
- **Planning** **Planning**
- Once an issue contains a Documentation label and the current milestone, a - Once an issue contains a Documentation label and an upcoming milestone, a
technical writer reviews the Product Manager's documentation requirements. technical writer reviews the Product Manager's documentation requirements
- Once the documentation requirements are approved, the technical writer can - Once the documentation requirements are approved, the technical writer can
work with the developer to discuss any documentation questions and plans/outlines, as needed. work with the developer to discuss any documentation questions and plans/outlines, if needed.
- **Review** - A technical writer must review the documentation for: **Review**
- Every documentation change beyond minor clarifications and corrections requires a Technical Writer review, with greater exceptions in place for GitLab Support.<!--TODO: link-->
This should apply to docs for every new or changed feature. The technical writer will ensure that the doc is clear, grammatically correct,
and discoverable, while avoiding redundancy, bad file locations, typos, broken links, etc. The technical writer must review the documentation for:
- Clarity - Clarity
- Relevance (make sure the content is appropriate given the impact of the feature) - Relevance (make sure the content is appropriate given the impact of the feature)
- Location (make sure the doc is in the correct dir and has the correct name) - Location (make sure the doc is in the correct dir 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 [docs style guide](styleguide.md) - Accordance to the [docs style guide](styleguide.md)
<!-- TODO: Clarify differences for completely new features vs. feature enhancemeents. May belong in structure doc. --> <!-- TODO: Clarify differences for completely new features vs. feature enhancemeents. May belong in structure doc. -->