This 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:
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:
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.
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:
When a new GitLab version is released on the 22nd, we release version-specific published documentation for the new version.
We complete the process as soon as possible after the GitLab version is announced. The result is:
-preappended to it, for example
Each documentation release:
To minimize problems during the documentation release process, use the following timeline:
Any time before the 17th of the month:
Between the 17th and the 20th of the month:
Create a release merge request for the new version, which updates the version dropdown menu for the current documentation and adds the release to the Docker configuration. For example, the release merge request for 13.9.
Try to create the MR close to the cutoff for
gitlab project's stable branch for the release.
gitlab-docs MR is too early or late, a mismatch between the
documentation files and the
gitlab-docs global navigation can cause failed MR pipelines that
must be manually fixed. To check the status of the
gitlab release, go to the
Slack channel and look for the
This is the candidate commit to be released on the 22nd.
On the 22nd of the month:
To add a new charts version for the release:
content/_data/chart_versions.yamland add the new stable branch version using the version mapping. Only the
major.minorversion is needed.
Note: If you have time, add anticipated future mappings to
content/_data/chart_versions.yaml. This saves
a step for the next GitLab release.
To create a stable branch of the
gitlab-docs project and a Docker image for the release:
Run the Rake task to create the single version. For example, to create the 13.9 release branch and perform other tasks:
A branch for the release is created, a new
Dockerfile.13.9 is created, and
has branches variables updated into a new branch. These files are automatically committed.
image:docs-singlejob creates a new Docker image tagged with the name of the branch you created earlier. You can see the Docker image in the
registryenvironment at https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry.
For example, see the 13.9 release pipeline.
If the pipeline fails, the new Docker image is not created and so not added to the registry.
Optionally, you can test locally by:
Building the image and running it. For example, for GitLab 13.9 documentation:
docker build -t docs:13.9 -f Dockerfile.13.9 . docker run -it --rm -p 4000:4000 docs:13.9
http://localhost:4000/13.9 to see if everything works correctly.
Note: An epic is open to automate this step.
To create the release merge request for the release:
Create a branch
release-X-Y. For example:
git checkout master git checkout -b release-13-9
content/_data/versions.yaml and update the lists of versions to reflect the new release:
offline:section. There should now be three versions in
Dockerfile.master by removing the oldest version, and then adding the newest version to the top of the list.
Commit and push to create the merge request. For example:
git add content/_data/versions.yaml Dockerfile.master git commit -m "Release 13.9" git push origin release-13-9
Releasedescription template. Set the merge request to Draft status and do not merge it yet.
content/_data/versions.yaml for all online versions (stable branches
X.Y of the
gitlab-docs project). For example:
Run the Rake task that creates all of the necessary merge requests to update the dropdowns. For example, for the 13.9 release:
git checkout release-13-9 ./bin/rake release:dropdowns
Visit the merge requests page to check that their pipelines pass. Set each merge request to draft status.
Do not merge these merge requests yet.
The merge requests for the dropdowns should now all be merged into their respective stable branches. Each merge triggers a new pipeline for each stable branch. Wait for the stable branch pipelines to complete, then:
Finally, run the
Build docker images weekly pipeline
that builds the
:latest Docker image.
As the last step in the scheduled pipeline, the documentation site deploys with all new versions.
Verify the documentation site has been deployed as expected. Open site
docs.gitlab.com in a
browser and confirm both the latest version and the correct
pre- version are listed in the
documentation version dropdown.
For example, if you released the 14.1 documentation, the first dropdown entry should be
GitLab.com (14.2-pre), followed by
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
/docdirectory were added, changed, or removed.
global nav item
release post item
development guidelines: See the Developer documentation for information about updating pages in the
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
If an issue/merge request has both the
Technical Writing and
labels, Technical Writers should add one of the following
to the issue/merge request 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::finished labels as
part of their content review).
The labels are used as follows:
Technical Writinglabel, as usual.
tw::doinglabel. 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::doinglabel (at least at the point of one work week of inactivity). Whenever work is restarted, the
tw::doinglabel is restored.
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
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
tw::doing scoped label to the issue/MR, and then continue with
the normal workflow process.
The Agile concept of weight allows tracking of the effort that it takes to complete work. Although GitLab has a Weight field for issues, the Technical Writing team is responsible for work that happens in both issues and merge requests. Other teams might also want to track their effort using the Weight field, so scoped labels allow writers to track effort without using the Weight field.
The following scoped labels allow the Technical Writing team to track effort in both issues and merge requests:
||Fix a single misspelling or add missing punctuation. Smallest amount of Technical Writing effort.|
||Develop or revise a few sentences. Most normal reviews would be at this level.|
||Develop or revise a section of content. More than a paragraph, less than a page.|
||Revise up to a full page with content provided to you, or develop approximately a half page from scratch.|
||Create an entirely new page for a feature or process, with no content provided in advance. Largest amount of technical writing effort. Split larger items into one or more issues or MRs.|
These labels are being tested by the team, and are not being used by all technical writers.
The technical writers using these labels assign a
tw-weight label to any issue or MR on which they work, based on the amount of effort to complete the task (which includes reviews). "Comparable effort" above provides some amount of consistency of the weights. However, each technical writer gauges their own level of effort. For example, if two technical writers were given a merge request to complete, one of them might rate their effort as 3 points, while the other might rate it as 8 points of effort, perhaps due to their unfamiliarity with the topic.
Because weights are based on each technical writers' assessment, they are not and will not be used for direct comparisons between technical writers. Weights can be used, however, to ensure individual technical writers have healthy workloads, and represent a mechanism that can indicate when they're getting overloaded with work.
Weights should not include time or effort associated with creating the issue or MR, or when dealing with pipeline or platform issues. For example, dealing with unforeseen build issues shouldn't be a factor in sizing, and wouldn't increase a 3 to a 5.
The first technical writer that works on the task (either as a reviewer of developer-created content, or as a developer of content) logs their effort with a
tw-weight label. The label isn't used to track the efforts of secondary technical writer reviewers.