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

Add more detail on deciding when to have TW review

This commit is contained in:
Mike Lewis 2019-01-30 17:48:08 +00:00
parent 55b8b3e2e4
commit ad8b8aa98c
1 changed files with 28 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -56,13 +56,16 @@ The Product Manager (PM) should confirm or add the following items in the issue:
- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md) (if applicable). - New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md) (if applicable).
- The documentation requirements for the developer working on the docs. - The documentation requirements for the developer working on the docs.
- What should the docs guide and enable the user to understand and accomplish? - What concepts and procedures should the docs guide and enable the user to understand and accomplish?
- To this end, what new page(s) are needed, if any? What pages/subsections need updates? For any guide or instruction set, should it help address one or more use cases? - 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.
- Consider user, admin, and API doc changes and additions. Consider whether we need to update a previously recommended workflow, or if we should link the new feature from various relevant places. Consider all ways documentation should be affected. - For any guide or instruction set, should it help address one or more use cases?
- Consider whether we need to update a previously recommended workflow, and if we should link the new feature from various relevant places. Consider all ways documentation should be affected.
- Include suggested titles of any pages or subsections, if applicable. - Include suggested titles of any pages or subsections, if applicable.
- Add the `Documentation` label to the issue. - Add the `Documentation` label to the issue.
Anyone is welcome to draft the items above in the issue, but a product manager must review and update any such content whenever the issue is assigned a specific milestone, and finalize this content by the kickoff. Anyone is welcome to draft the items above in the issue, but a product manager must:
- Review and update any such content whenever the issue is assigned a specific milestone.
- Finalize this content by the kickoff.
### 2. Developer roles ### 2. Developer roles
@ -72,10 +75,15 @@ As a developer, you must ship the documentation with the code of the feature tha
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. Technical writers are happy to help, as requested and planned on an issue-by-issue basis.
- New and edited docs should be included in the MR introducing the code, and planned Follow the process below unless otherwise agreed with the product manager and technical writer for a given issue:
in the issue that proposed the feature. However, if the new or changed doc requires
extensive collaboration or conversation, a separate, linked issue can be used for the planning process. - Include any new and edited docs in the MR introducing the code.
We are trying to avoid using a separate MR, so the docs stay with the code, but the - Use the Documentation requirements confirmed by the Product Manager in the
issue. Discuss any ideas or changes to these requirements in the issue, before you begin,
and in the MR, once you begin work.
- 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. 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 Documentation [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/).
@ -92,10 +100,16 @@ All reviewers can help ensure accuracy, clarity, completeness, and adherence to
- Prior to merge, documentation changes committed by the developer must be reviewed by: - Prior to merge, documentation changes committed by the developer must be reviewed by:
1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness. 1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness.
2. Optionally: Others involved in the work, such as other devs or the PM. 1. Optionally: Others involved in the work, such as other devs or the PM.
3. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge. 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. 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.
4. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. - 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.
- 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). - 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).
@ -115,7 +129,7 @@ This is not a blocking review and developers should not wait to work on docs.
**Review** **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
there's time before the freeze, the technical writer's review can commence early, on request. 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,