GitLab Professional Services
Accelerate your software lifecycle with help from GitLab experts
Popular GitLab use cases
Enterprise Small Business Continuous Integration (CI/CD) Source Code Management (SCM) Out-of-the-box Pipelines (Auto DevOps) Security (DevSecOps) Agile Development Value Stream Management GitOpsGitLab Professional Services
Accelerate your software lifecycle with help from GitLab experts
Popular GitLab use cases
Enterprise Small Business Continuous Integration (CI/CD) Source Code Management (SCM) Out-of-the-box Pipelines (Auto DevOps) Security (DevSecOps) Agile Development Value Stream Management GitOpsThis document explains the workflows of the Technical Writing team.
These processes work in conjunction with the:
The process for creating and maintaining GitLab product documentation depends on whether the documentation is:
A new feature or feature enhancement.
Delivered for a specific milestone and associated with specific code changes. This documentation has the highest priority.
Changes outside a specific milestone.
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 ~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:
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.
#docs
on GitLab Slack, if you:
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:
gitlab-org/gitlab
repo). The entry can be a path if all its files are
owned by the same group; otherwise include references to individual files.The Technical Writer:
~feature
issues that are part of the next milestone
to get a sense of the scope of content likely to be authored.~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.~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.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.
Technical Writers:
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 in accordance with review principles.
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.
Additional information about composing and reviewing UI text:
The Technical Writer for each stage group is a reviewer of their group's feature blocks (also known as release post items) authored by the Product Manager.
For each release, a single Technical Writer is also assigned as the Technical Writing Lead to perform the Structural Check and other duties.
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 information about labels as described in this section supplements the contents of the Issues workflow page. To view a usage description of each of the labels in this section, see Labels in the GitLab interface.
Any issue or merge request for which a Technical Writer provides a measurable
amount of work on (including content creation and reviews) must include the
Technical Writing
label.
After adding the Technical Writing
label, we want to classify the type of
effort we're contributing to the issue or merge request by adding an additional
label from the following list:
documentation
:
Use this label if files in the /doc
directory were added, changed, or
removed.UI text
global nav item
release post item
tw-style
tw-testing
development guidelines
:
See the Developer documentation
for information about updating pages in the /developer
directory.docs-technical-debt
handbook
Depending on the issue or merge request, you may include one or more of the
preceding labels with the issue or merge request, depending on its contents.
There may be occasions when none of the preceding labels apply to the issue
or merge request; in that case, having only the Technical Writing
label is
enough.
If an issue/merge request has both the Technical Writing
and documentation
labels, Technical Writers should add one of the following
scoped labels
to the issue/merge request on which they work:
docs::feature
docs::fix
docs::improvement
docs::non-content
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:
tw::doing
tw::finished
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:
Technical Writing
label, as usual.tw::doing
label. In this case, work is everything that's required to
finish the content, from creation through review. If a writer involved in
the process stops working on the unfinished issue/MR, they remove the
tw::doing
label (at least at the point of one work week of inactivity).
Whenever work is restarted, the tw::doing
label is restored.tw::finished
label.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.