diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 8629f62ffdf..afb92b35f4b 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -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). - The documentation requirements for the developer working on the docs. - - What 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? - - 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. + - 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? Consider user, admin, and API doc changes and additions. + - 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. - 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 @@ -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. 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 -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. -We are trying to avoid using a separate MR, so the docs stay with the code, but the +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 +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. - 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/). @@ -91,11 +99,17 @@ the feature cannot be included with the release.