This document explains the workflows of the Technical Writing team.
These processes work in conjunction with the Product development flow, Product designer workflow, and Engineering workflow, and the broader information about contributing to GitLab found in PROCESS.md.
The process for creating and maintaining GitLab product documentation depends on whether the documentation is:
Delivered for a specific milestone and associated with specific code changes. This documentation has the highest priority.
Usually not associated with a specific code change, is of lower priority, and is open to all GitLab contributors. The process for these changes are documented in GitLab's documentation.
Documentation isn't usually required when a backstage feature is added or changed, and doesn't directly affect the way that any user or administrator interacts with GitLab.
Documentation is required for any new or changed feature, and is:
Documentation for specific milestones involves the:
Each role is described below.
Developers are the primary author of documentation for a feature or feature enhancement. They are responsible for:
Note: Community Contributors can ask for additional help from GitLab team members.
Because the documentation is an essential part of the product, if a
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:
Use the 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.
#docson GitLab Slack, if you:
Reviewers help ensure:
Prior to merging, documentation changes committed by the developer must be reviewed by:
Product Managers are responsible for the documentation requirements for a feature or feature enhancement. They can also:
For issues requiring any new or updated documentation, the Product Manager must:
Everyone is encouraged to draft the documentation requirements in the issue. However, a Product Manager will:
Technical Writers are responsible for:
The Technical Writer:
~featureissues that are part of the next milestone to get a sense of the scope of content likely to be authored.
~documentationlabel on issues from that list which don't have it but should, or inquires with the PM to determine if documentation is truly required.
~directionissues 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.
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.
The Technical Writer will review the documentation to check that the developer and code reviewer have ensured:
Documentation is required for a milestone when:
Note: Documentation refactoring unrelated to a feature change is covered by the process for changes not related to a specific milestone, which allows for time-sensitive documentation updates to be prioritized.
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 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:
Currently, the Technical Writing team strongly encourages including documentation in the same merge request as the code that it relates to, but this isn't 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 documentation is included in the code MR, as part of their definition of done. When a team adopts this workflow, that team's engineers must include their documentation in the same MR as their feature code, at all times.
A workflow that has documentation separated into its own MR has many downsides.
If the documentation merges before the feature:
If the documentation merges after the feature:
Having two separate MRs means:
Documentation quality might be lower, because:
Including documentation with code (and doing it early in the development process) has many benefits:
In order to have documentation included with code as a mandatory workflow, some changes might need to happen to a team's current workflow:
Maintainers are allowed to merge features with the documentation as-is, even if the technical writer hasn't given final approval yet but the merge request has all other required approvals.
You can visualize the parallel workflow for code and documentation reviews as:
For complex features split over multiple merge requests:
A Product Designer should consult with the Technical Writer for their stage group when planning to add or change substantial text within the UI, such as a phrase of explanatory microcopy or a link to documentation.
The technical writer can offer an initial review of any ideas, plans, or actual text, and can be asked to draft text when provided with information on the context and goals of the text. Context may include detail on the scenarios in which the text would appear (for example, to all users viewing the feature or only under certain conditions), and the information to convey, which typically answers one or more of the questions:
Once the merge request is created, all changes and additions to text in the UI must be reviewed by the Technical Writer. These may include labels (buttons, menus, column headers, UI sections) or any phrases that may be displayed within the UI, such as user-assistance microcopy or error messages.
Technical writers should familiarize themselves with these Pajamas Design System pages, use them when working with UI Copy, and contribute improvements to them if possible:
Additional information about composing and reviewing UI text:
For each release, a single technical writer is also assigned to the Release Post Structural Check.
When working with issues or merge requests, the Technical Writing team uses labels to describe those issues' and merge requests' attributes (including the types of work being done).
The Technical Writers add the following labels to the issues and MRs on which they work:
To better communicate the status of what's being worked on by the Technical Writing team, the Technical Writers use the following labels to describe issues' statuses:
Note that these are team workflow labels. The Technical Writer who is doing writing work will usually be the person adding the ~"tw::doing" label, and the Technical Writer doing the review will usually be changing it to the ~"tw::finished" label (although external content submissions could have the same Technical Writer using both the ~"tw::doing" and ~"tw::finished" labels as part of their content review).
The labels are used as follows:
Note that the ~"tw::finished" label is for indicating when a Technical Writer is done with an issue/MR for which we're not doing the merge or closing the issue. If the Technical Writing team is doing the merging/closing, the issue/MR status overrides the scoped "tw" label status, and there's no need to use the ~"tw::finished" label.
If a Technical Writer is presented with an open issue or MR with a ~"tw::finished" label that has more work required for it, the writer should re-add the ~"tw::doing" scoped label to the issue/MR, and then continue with the normal workflow process.