diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index b204daec6b0cdee04c1a8e9564ab09462aa687c6..74339db7a7999b56f1a3dbb36e41f4afab26b848 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -41,6 +41,27 @@ When revamping documentation, if unrelated to the feature change, this should be 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. +## Documentation requirements + +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. + ## Documenting a new or changed feature To follow a consistent workflow every month, documentation changes @@ -52,20 +73,19 @@ and default merge request template will assist you with following this process. ### 1. Product Manager's role -The Product Manager (PM) should confirm or add the following items in the issue: +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. -- 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 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. +Everyone is encouraged to draft the requirements in the issue, but a product manager will +do the following: -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. +- When the issue is assigned a release milestone, review and update the Documentation details. +- By the kickoff, finalizie the Documentation details. ### 2. Developer roles