diff options
Diffstat (limited to 'doc/development/documentation/workflow.md')
| -rw-r--r-- | doc/development/documentation/workflow.md | 382 |
1 files changed, 14 insertions, 368 deletions
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 01f528dcfa4..ab6200155bf 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,19 +1,20 @@ # Documentation process -The process for creating and maintaining GitLab product documentation depends on whether the -documentation is associated with: +The process for creating and maintaining GitLab product documentation allows +anyone to contribute a merge request or create an issue for GitLab's +documentation. -- [A new feature or feature enhancement](#for-a-product-change). - - Delivered for a specific milestone and associated with specific code changes. This documentation - has the highest priority. +NOTE: **Note:** +Documentation updates relating to new features or feature enhancements must +use the [feature workflow process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) described in the GitLab Handbook. -- [Changes outside a specific milestone](#for-all-other-documentation). +## Who updates the docs? - It is usually not associated with a specific code change and has a lower priority. +*Anyone* can contribute! You can create a merge request for documentation when: -Documentation is not usually required when a "backstage feature" is added or changed, and does not -directly affect the way that any user or administrator interacts with GitLab. +- You find errors or other room for improvement in existing documentation. +- You have an idea for all-new documentation that would help a GitLab user or administrator to + accomplish their work with GitLab. ## Documentation labels @@ -32,372 +33,17 @@ The following are also added by members of the Technical Writing team: `docs::` prefix. For example, `~docs::improvement`. - The `~Technical Writing` [team label](../contributing/issue_workflow.md#team-labels). -## For a product change - -This documentation is required for any new or changed feature and is: - -- Created or updated as part of feature development, almost always in the same merge request as the - feature code. Including documentation in the same merge request as the code eliminates the - possibility that code and documentation get out of sync. -- Required with the delivery of a feature for a specific milestone as part of GitLab's - [definition of done](../contributing/merge_request_workflow.md#definition-of-done). -- Often linked from the release post. - -### Roles and responsibilities - -Documentation for specific milestones involves the: - -- Developer of a feature or enhancement. -- Product Manager for the group delivering the new feature or feature enhancement. -- Technical Writer assigned to the group. - -Each role is described below. - -#### Developers - -Developers are the primary author of documentation for a feature or feature enhancement. They are -responsible for: - -- Developing initial content required for a feature. -- Liaising with their Product Manager to understand what documentation must be delivered, and when. -- Requesting technical reviews from other developers within their group. -- Requesting documentation reviews from the Technical Writer - [assigned to the DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) - that is delivering the new feature or feature enhancements. - -TIP: **Tip:** -Community Contributors can ask for additional help from GitLab team members. - -##### Authoring - -Because the documentation is an essential part of the product, if a ~feature issue also contains the -~documentation label, you must ship the new or updated documentation with the code of the feature. - -Technical Writers are happy to help, as requested and planned on an issue-by-issue basis. - -For feature issues requiring documentation, follow the process below unless otherwise agreed with -the Product Manager and Technical Writer for a given issue: - -- Include any new and edited documentation, either in: - - The merge request introducing the code. - - A separate merge request raised around the same time. -- Use the [documentation requirements](#documentation-requirements) developed by the Product Manager - in the issue and discuss any further documentation plans or ideas as needed. - - If the new or changed documentation requires extensive collaboration or conversation, a - separate, linked issue can be used for the planning process. - -- Use the [Documentation guidelines](index.md), as well as other resources linked from there, - including: - - Documentation [Structure and template](structure.md) page. - - [Style Guide](styleguide.md). - - [Markdown Guide](https://about.gitlab.com/handbook/engineering/ux/technical-writing/markdown-guide/). -- Contact the Technical Writer for the relevant [DevOps stage](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) - in your issue or merge request, or within `#docs` on GitLab Slack, if you: - - Need any help to choose the correct place for documentation. - - Want to discuss a documentation idea or outline. - - Want to request any other help. -- If you are working on documentation in a separate merge request, ensure the documentation is - merged as close as possible to the code merge. -- A policy for documenting [feature-flagged](../feature_flags/index.md) issues is forthcoming and you - are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab/issues/26347). - -##### Reviews and merging - -Reviewers help ensure: - -- Accuracy. -- Clarity. -- Completeness. -- Adherence to: - - [Documentation requirements](#documentation-requirements) in the issue. - - [Documentation guidelines](index.md). - - [Style guide](styleguide.md). - -Prior to merging, documentation changes committed by the developer must be reviewed by: - -- The code reviewer for the merge request. This is known as a technical review. -- Optionally, others involved in the work such as other developers or the Product Manager. -- The Technical Writer for the DevOps stage group, except in exceptional circumstances where a - [post-merge review](#post-merge-reviews) can be requested. -- A maintainer of the project. - -#### Product Managers - -Product Managers are responsible for the [documentation requirements](#documentation-requirements) -for a feature or feature enhancement. They can also: - -- Liaise with the Technical Writer for discussion and collaboration. -- Review documentation themselves. - -For issues requiring any new or updated documentation, the Product Manager 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 when applicable (as required by the - [documentation structure and template](structure.md)). - -Everyone is encouraged to draft the documentation requirements in the issue. However, a Product -Manager will: - -- When the issue is assigned a release milestone, review and update the Documentation details. -- By the kickoff, finalize the documentation details. - -#### Technical Writers - -Technical Writers are responsible for: - -- Participating in issues discussions and reviewing MRs for the upcoming milestone. -- Reviewing documentation requirements in issues when called upon. -- Answering questions, and helping and providing advice throughout the authoring and editing - process. -- Reviewing all significant new and updated documentation content, whether before merge or after it - is merged. -- Assisting the developer and Product Manager with feature documentation delivery. - -##### Planning - -The Technical Writer: - -- Reviews their group's `~feature` issues that are part of the next milestone to get a sense of the - scope of content likely to be authored. -- Recommends the `~documentation` label on issues from that list which don't have it but should, or - inquires with the PM to determine if documentation is truly required. -- For `~direction` issues from that list, reads the full issue and reviews its Documentation - requirements section. Addresses any recommendations or questions with the PMs and others - collaborating on the issue in order to refine or expand the Documentation requirements. - -##### Collaboration - -By default, the developer will work on documentation changes independently, but -the developer, Product Manager, or Technical Writer can propose a broader collaboration for -any given issue. - -Additionally, Technical Writers are available for questions at any time. - -##### Review - -Technical Writers: - -- Provide non-blocking reviews of all documentation changes, before or after the change is merged. -- Confirm that the documentation is: - - Clear. - - Grammatically correct. - - Discoverable. - - Navigable. -- Ensures that the documentation avoids: - - Redundancy. - - Bad file locations. - - Typos. - - Broken links. - -The Technical Writer will review the documentation to check that the developer and -code reviewer have ensured: - -- Clarity. -- Appropriate location, making sure the documentation is in the correct directories (often - reflecting how the product is structured) and has the correct name. -- Syntax, typos, and broken links. -- Improvements to the content. -- Accordance with the: - - [Documentation Style Guide](styleguide.md). - - [Structure and Template](structure.md) doc. - -### When documentation is required - -Documentation [is required](../contributing/merge_request_workflow.md#definition-of-done) for a -milestone when: - -- A new or enhanced feature is shipped that impacts the user or administrator experience. -- There are changes to the UI or API. -- A process, workflow, or previously documented feature is changed. -- A feature is deprecated or removed. - -NOTE: **Note:** -Documentation refactoring unrelated to a feature change is covered in the -[other process](#for-all-other-documentation), so that time-sensitive documentation updates are -prioritized. - -### 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. Issues -created using the [**Feature Proposal** template](https://gitlab.com/gitlab-org/gitlab/raw/master/.gitlab/issue_templates/Feature%20proposal.md) -have this section by default. - -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 on request. - -The following details should be included: - -- What concepts and procedures should the documentation guide and enable the user to understand or - accomplish? -- To this end, what new page(s) are needed, if any? What pages or subsections need updates? - Consider changes and additions to user, admin, and API documentation. -- 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 documentation is - found in relevant searches? -- Include suggested titles of any pages or subsection headings, if applicable. -- List any documentation that should be cross-linked, if applicable. - -### Including docs with code - -Currently, the Technical Writing team strongly encourages including documentation in -the same merge request as the code that it relates to, but this is not strictly mandatory. -It's still common for documentation to be added in an MR separate from the feature MR. - -Engineering teams may elect to adopt a workflow where it is **mandatory** that docs -are included in the code MR, as part of their [definition of done](../contributing/merge_request_workflow.md#definition-of-done). -When a team adopts this workflow, that team's engineers must include their docs in the **same** -MR as their feature code, at all times. - -#### Downsides of separate docs MRs - -A workflow that has documentation separated into its own MR has many downsides. - -If the documentation merges **before** the feature: - -- GitLab.com users might try to use the feature before it's released, driving support tickets. -- If the feature is delayed, the documentation might not be pulled/reverted in time and could be - accidentally included in the self-managed package for that release. - -If the documentation merges **after** the feature: - -- The feature might be included in the self-managed package, but without any documentation - if the docs MR misses the cutoff. -- A feature might show up in the GitLab.com UI before any documentation exists for it. - Users surprised by this feature will search for documentation and won't find it, possibly driving - support tickets. - -Having two separate MRs means: - -- Two different people might be responsible for merging one feature, which is not workable - with an asynchronous work style. The feature might merge while the technical writer is asleep, - creating a potentially lengthy delay between the two merges. -- If the docs MR is assigned to the same maintainer as responsible for the feature - code MR, they will have to review and juggle two MRs instead of dealing with just one. - -Documentation quality might be lower, because: - -- Having docs in a separate MR will mean far fewer people will see and verify them, - increasing the likelihood that issues will be missed. -- In a "split" workflow, engineers might only create the documentation MR once the - feature MR is ready, or almost ready. This gives the technical writer little time - to learn about the feature in order to do a good review. It also increases pressure - on them to review and merge faster than desired, letting problems slip in due to haste. - -#### Benefits of always including docs with code - -Including docs with code (and doing it early in the development process) has many benefits: - -- There are no timing issues connected to releases: - - If a feature slips to the next release, the documentation slips too. - - If the feature *just* makes it into a release, the docs *just* make it in too. - - If a feature makes it to GitLab.com early, the documentation will be ready for - our early adopters. -- Only a single person will be responsible for merging the feature (the code maintainer). -- The technical writer will have more time to gain an understanding of the feature - and will be better able to verify the content of the docs in the Review App or GDK. - They will also be able to offer advice for improving the UI text or offer additional use cases. -- The documentation will have increased visibility: - - Everyone involved in the merge request will see the docs. This could include product - managers, multiple engineers with deep domain knowledge, as well as the code reviewers - and maintainer. They will be more likely to catch issues with examples, as well - as background or concepts that the technical writer may not be aware of. - - Increasing visibility of the documentation also has the side effect of improving - *other* engineers' documentation. By reviewing each other's MRs, each engineer's - own documentation skills will improve. -- Thinking about the documentation early can help engineers generate better examples, - as they will need to think about what examples a user will want, and will need to - make sure the code they write implements that example properly. - -#### Docs with code as a workflow - -In order to have docs included with code as a mandatory workflow, some changes might -need to happen to a team's current workflow: - -- The engineers must strive to include the docs early in the development process, - to give ample time for review, not just from the technical writer, but also the - code reviewer and maintainer. -- Reviewers and maintainers must also review the docs during code reviews, to make - sure the described processes match the expected use of the feature, and that examples - are correct. They do *not* need to worry about style, grammar, and so on. -- The technical writer must be assigned the MR directly and not only pinged. Thanks - to the ability to have [multiple assignees for any MR](../../user/project/merge_requests/getting_started.md#multiple-assignees-starter), - this can be done at any time, but must be before the code maintainer review. It's - common to have both the docs and code reviews happening at the same time, with the - author, reviewer and technical writer discussing the docs together. -- When the docs are ready, the technical writer will click **Approve** and usually - will no longer be involved in the MR. If the feature changes during code review and - the docs are updated, the technical writer must be reassigned the MR to verify the - update. -- Maintainers are allowed to merge features with the docs "as-is", even if the technical - writer has not given final approval yet. The **docs reviews must not be blockers**. Therefore - it's important to get the docs included and assigned to the technical writers early. - If the feature is merged before final docs approval, the maintainer must create - a [post-merge follow-up issue](#post-merge-reviews), and assign it to both the engineer - and technical writer. - -Maintainers are allowed to merge features with the docs "as-is" even if the -technical writer has not given final approval yet but the merge request has -all other required approvals. - -You can visualize the parallel workflow for code and docs reviews as: - -```mermaid -graph TD - A("Feature MR Created (Engineer)") --> |Assign| B("Code Review (reviewer)") - B --> |"Approve / Reassign"| C("Code Review (maintainer)") - C --> |Approve| F("Merge (maintainer)") - A --> D("Docs Added (Engineer)") - D --> |Assign| E("Docs Review (Tech Writer)") - E --> |Approve| F -``` - -For complex features split over multiple merge requests: - -- If a merge request is implementing components for a future feature, but the components - are not accessible to users yet, then no documentation should be included. -- If a merge request will expose a feature to users in any way, such as an enabled - UI element, an API endpoint, or anything similar, then that MR **must** have docs. - Note that this may mean multiple docs additions could happen in the buildup to the - implementation of a single large feature, for example API docs and feature usage docs. -- If it's unclear which engineer should add the feature documentation into their - MR, the engineering manager should decide during planning, and tie the documentation - to the last MR that must be merged before a feature is considered released. - This is often, but not always, a frontend MR. - -## For all other documentation - Documentation changes that are not associated with the release of a new or updated feature do not take the `~feature` label, but still need the `~documentation` label. They may include: - Documentation created or updated to improve accuracy, completeness, ease of use, or any reason - other than a [feature change](#for-a-product-change). + other than a [feature change](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change). - Addressing gaps in existing documentation, or making improvements to existing documentation. - Work on special projects related to the documentation. -TIP: **Tip:** -Anyone can contribute a merge request or create an issue for GitLab's documentation. - -### Who updates the docs - -Anyone can contribute! You can create a merge request for documentation when: - -- You find errors or other room for improvement in existing documentation. -- You have an idea for all-new documentation that would help a GitLab user or administrator to - accomplish their work with GitLab. - -### How to update the docs +## How to update the docs To update GitLab documentation: @@ -464,7 +110,7 @@ The process involves the following: The process is reflected in the **Documentation** [merge request template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md). -### Other ways to help +## Other ways to help If you have ideas for further documentation resources please [create an issue](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Documentation) |