The GitLab Technical Writing team collaborates with developers, product managers, and the community to develop product documentation.
Good documentation meets the evolving needs of GitLab customers, users, and administrators. It educates readers about features and best practices. It enables people to efficiently configure, use, and troubleshoot GitLab. The Technical Writing team manages the docs.gitlab.com site and its content, processes, and tooling.
The documentation roadmap drives our efforts to improve both the content and documentation website. For example, we know that people have trouble finding information on docs.gitlab.com. We have roadmap items and OKRs to replatform the docs site, provide better task-based information, and make content easier to find. These larger projects, completed in addition to feature documentation, provide continual, iterative improvement to the user experience of our documentation.
Team members are assigned to specific DevOps stage groups. The Technical Writing team is broadly responsible for both developing documentation content and UI text, and helping others while they develop content:
Maintaining documentation for many engineering projects.
Occasionally developing new content to meet the needs of the community.
Reviewing and collaborating on documentation plans, reviewing doc merge requests or recently merged docs, and ensuring that content meets style and language standards.
Reorganizing, revamping, and authoring improved documentation to ensure completeness and a smooth user experience.
Collaborating with Product Designers on UI text, such as microcopy, links from the UI to documentation, error messages, and UI element labels.
Acting as Technical Writing Lead for the monthly release post.
Prioritization
When evaluating work to meet our stakeholders’ needs, we prioritize in the following order:
Feature work (including documenting new features, and providing guidance on UI text)
All other tasks (including creating suggestion- or warning-level Vale rules)
Processes
The team is responsible for developing and maintaining efficient processes, including:
Ensuring that processes are in place and being followed to keep the GitLab docs up to date.
Following and optimizing documentation workflows with Product and Engineering, Documentation Team workflows, and the division of work.
Triaging doc-related issues.
Refining the Documentation Style Guide and continuously improving content about GitLab documentation and its contribution process.
Making it easier for anyone to contribute to the documentation while efficiently handling community contributions to docs.
Style Guide
The Documentation Style Guide
provides language and style guidance for the product documentation and release posts.
Any Technical Writer (or other contributor) can make suggestions for
documentation style updates or additions by creating an issue or merge request with the
~tw-style label, and then assigning the issue or MR to the Style Guide DRI. GitLab team members can also use the #docs Slack channel.
Use the following searches to track completed style-related issues:
The Technical Writing team develops and maintains toolkits to test GitLab’s documentation (and other technical content) for problems. These toolkits include (but aren’t limited) to:
Text content and writing style: markdownlint, Vale
Text formatting: markdownlint, yamllint
Link validity: Nanoc
File permissions and naming: lint-doc.sh
Any contributor can suggest changes to our linting rules or tooling by creating an issue or merge request with the ~tw-testing label, and then assigning the issue or MR to a Technical Writer.
Translation and internationalization
Everyone can contribute to the translation of GitLab from English into other languages.
To learn more about translation and internationalization at GitLab, visit the Import and Integrate direction page and Manage stage Category Direction page on Internationalization.
For a step-by-step guide to translation contributions, read Translating GitLab.
The docs.gitlab.com site is not included in the community efforts to internationalize GitLab. Discussion on translating documentation into other languages is included in this issue.
The designated Technical Writer is the go-to person for their assigned
groups. They collaborate with
other team members to plan new documentation, edit existing documentation,
review any proposed changes to documentation, suggest changes to UI microcopy,
and generally partner with subject matter experts (SMEs) in
all situations where documentation is required.
If you were directed here from a documentation page’s metadata:
The metadata doesn’t indicate developer ownership, but is meant to direct you to an appropriate Technical Writer.
If you are part of a development group and would like to add metadata to documentation pages, create an issue in the TW team tasks project for discussion. Additional discussion is in issue 547.
Technical Writers are encouraged to review and improve documentation of other
stages but they aren’t required to. When contributing to docs they don’t own,
they must respect the assigned TW’s ownership and ensure to request their review
and approval when adding significant changes to their docs.
When a Technical Writer is on PTO, the whole team acts as their backup.
The doc/development directory. Any Maintainer can merge docs in the doc/development directory.
The only exception is /doc/development/documentation, where the writers maintain guidelines.
The doc/solutions directory. This information is created, reviewed, merged, and maintained by Solutions Architects.
Stable counterparts
The Technical Writing team gets assistance with the gitlab-docs project from stable counterparts outside the team.
The technical writing team supports a large amount of content.
Page count
The number of pages in the five primary repositories (GitLab, Omnibus, Charts, Operator, and Runner):
Date
# of pages
Increase/decrease from previous quarter
Dec 2024
2,442
5 %
Sept 2024
2,328
-5 %
June 2024
2,456
6 %
Mar 2024
2,308
5 %
Dec 2023
2,201
5 %
Sept 2023
2,088
8 %
Jun 2023
1,993
5 %
Mar 2023
1,929
3 %
Dec 2022
1,840
-
Sept 2022
1,785
-
June 2022
1,633
-
Jan 2022
1,562
-
May 2020
1,165
-
Change between May 2020 and December 2024: 1,277 more pages (a 110% increase).
Decrease in September 2024 due to moving the architecture blueprints topics to the handbook. For more information, see issue 279.
Page count by area of the left nav
In December, 2024, the page count by area of the left navigation:
Word count
The number of words in these repositories:
Date
Word count
Increase/decrease from previous quarter
Dec 2024
3,373,709
6 %
Sept 2024
3,191,353
-4 %
June 2024
3,325,823
4 %
Mar 2024
3,183,647
6 %
Dec 2023
2,990,400
5 %
Sept 2023
2,842,399
5 %
Jun 2023
2,701,888
6 %
Mar 2023
2,546,466
6 %
Dec 2022
2,397,335
-
Oct 2022
2,271,350
-
June 2022
2,166,052
-
Jan 2022
2,017,183
-
May 2020
1,190,371
-
Change between May 2020 and December 2024: 2,183,338 more words (a 183% increase).
Decrease in September 2024 due to moving the architecture blueprints topics to the handbook. For more information, see issue 279.
The word count has more than doubled in this timeframe.
Word count by area of the left nav
In December, 2024, the word count by area of the left navigation:
Analytics
GitLab Team Members can view docs site metrics on the docs.gitlab.com LookerStudio dashboard.
To view page level analytics, select Page views by month, and add the page URL in the value field. Do not include https:// as part of the value.
When Technical Writers take paid time off, the rest of the team provides coverage for them.
These team members may require additional context for requests. Requests are incorporated into the list of stage/group and
feature priorities for their primary groups.
Options for groups to get help when an assigned Technical Writer is on PTO are:
Reviewer Roulette.
A rouletted Technical Writer can be pinged or assigned to an issue or merge request.
A request in the #docs channel in Slack, where it will be picked
up by an available volunteer Technical Writer.
For help with a specific, time-sensitive, in-progress piece of work, a pre-arranged Technical Writer. The Technical
Writer can be pinged on issues or merge requests and begin participating.
If taking extended PTO (one week or more), Technical Writers and Managers should use the Technical Writer
coverage issue.
This issue can describe exactly who is providing coverage, for what, and by what means.
Taking PTO
When taking PTO, Technical Writers:
Ensure their out-of-office messaging reflects the available mechanisms for coverage.
It’s important to keep GitLab.com statuses up-to-date to ensure:
The TW team can easily see the PTO status of all team members when checking the Roulette dashboard.
Send a message in the group Slack channels indicating where to find the available mechanisms. For example:
I'm off for the holidays (202y-mm-dd - 202y-mm-dd). For help with documentation while I'm away, see
https://handbook.gitlab.com/handbook/product/ux/technical-writing/#technical-writer-pto for ways to get help.
For urgent _named time-sensitive task_ matters, ping _named TW_.
Merge request queue checks
Before a Technical Writer goes on PTO, the writer or their manager should determine who will check the writer’s MR queue. The assigned person should check the queue at least once each day in the GitLab Review Workload Dashboard.
The assigned writer does not need to do the work. When they check the queue, they can:
Assign the MRs to themselves for review.
Use Roulette to find other TWs to review.
Regularly scheduled tasks
Along with Technical Writers’ normally assigned work, there are recurring tasks
that need to be regularly completed:
Release Post Structural Check: The Technical Writing Lead reviews the content for the release post published at the end of each milestone. See the Release Post Scheduling Handbook page for each milestone’s assigned writer.
Monthly doc version: At the end of each milestone, a Technical Writer creates the monthly version for the docs site. The Technical Writer assigned to this task is the writer who completed the release post structural check for the previous milestone.
Docs project maintenance tasks:ON HOLD from February 2025 as we complete our migration to Hugo. Each month, one Technical Writer is assigned to complete maintenance tasks for the documentation site and its content. This involves creating a new issue using the tw-monthly-tasks template in the technical-writing project to track maintenance work. If additional work beyond what’s described in the maintenance issue is required, the Technical Writer creates merge requests and additional issues as needed.
these tasks at this time.**
Technical Writers are assigned to review merge requests that contain documentation changes authored by GitLab team members and community contributors. The reviews are assigned by subject matter according to the Technical Writer assignments to stage groups or other specialties.
Levels of edit
The Technical Writers use the following levels of edit:
Light
Ensure the pipeline passes and no obvious grammar, spelling, or punctuation errors exist.
Medium
Ensure the pipeline passes and no grammar, spelling, or punctuation errors exist.
Ensure the content is clear, discoverable, navigable, and written with the user’s perspective in mind.
In all cases, the Technical Writer confirms that an authoritative source has checked the documentation for technical accuracy.
The Technical Writer can serve as that authoritative source if they have the required knowledge or
can efficiently perform the necessary verification.
Review workflow
To balance velocity and quality, the Technical Writers use this workflow:
When a Technical Writer opens a merge request, another Technical Writer must review and merge.
The Technical Writer should not approve or merge their own MR. Instead, they should request a review from a peer with Maintainer access. The reviewer merges the MR after the final approval.
When anyone else (like a developer, community member, or Support team member) opens a merge request:
If the MR contains only documentation changes, the Technical Writer:
Reviews the content and offers suggestions.
Does not directly make large changes (by applying suggestions or pushing commits) to the author’s branch unless they have explicit approval in the MR to do so.
Pushing to a branch can cause hard-to-resolve merge conflicts, and content can be accidentally overwritten.
Can use suggestions or commits to make changes themselves only if the writer has agreement from the author to make changes directly to the author’s branch.
In these cases, the author must always review the Technical Writer’s changes before the writer merges, to help ensure accuracy.
Can apply small suggestions using the Apply suggestion feature if an MR is nearly ready to merge.
Writers can fix things like missing punctuation, typos, and pipeline failures without additional review.
Approves and merges the documentation MR when it is ready.
If the MR is primarily a code change that also contains a documentation update, the Technical Writer:
Offers suggestions for any documentation, UI text, and error message changes, but should not apply any suggestion themselves.
Making any changes to a code MR can cause pipelines to fail as code and specs often need to be updated by the engineer to match technical writing suggestions.
Approves the MR if the documentation changes are ready to merge.
Does not merge code MRs. The MR must be merged by an engineer who also reviews the code change.
If the MR is primarily a documentation change, but also has a small code change to update a link to match the change, the Technical Writer:
Reviews the content using the same workflow as a documentation-only MR.
When a bot or a community contributor mentions either @gl-docsteam or several Technical Writers based on CODEOWNERS, TWs should volunteer to:
Scan the MR and either volunteer to review it or determine which TW should review it, following the guidelines in Selecting a reviewer.
Then, if the MR:
Seems ready for review, assign the selected TW as a reviewer.
Doesn’t seem ready for review, leave a comment for the contributor asking them to mention the selected TW when they’re ready.
Edit the bot’s comment and format the team mention as code. For example: Hi `@gl-docsteam`! Please review this documentation merge request. This removes other TWs from the MR’s participants list, and they will no longer receive notifications for it. The to-do notification will be updated to show the username in backticks, so team members working from their to-do list will have a visible hint that the MR has been addressed.
Selecting a reviewer
In most cases, Technical Writers should use the GitLab Review Workload Dashboard to identify someone for a technical writing review. Be sure the page’s filter is set to show only Technical Writers and sort by Assign events last 7 days.
To get an available Technical Writer, select Spin the wheel! on the Dashboard page. In the specific cases where the selected Technical Writer already has a lot of assigned reviews or has recently been very busy, you can select Spin the wheel! again to get a different writer.
If you have content that needs a specific assignee, or if you have a merge request for a page that has a DRI (such as the Documentation Style Guide), in those cases you can specifically assign the review to that person.
Determining Technical Writer availability
There are occasions when Technical Writers may be too busy for general team merge request reviews, and need to focus on their groups or other priorities. In those cases, Technical Writers can update their GitLab status by selecting the Busy checkbox and adding the 🔴 :red_circle:, which prevents their name from appearing in the reviewer roulette.
For example, Technical Writers on release duty for a milestone should add the busy indicator to their status for the week preceding the release date, to focus on release posts and other requirements.
In all other cases, while Technical Writers can add (and remove) the busy indicator from their profiles, we ask that the busy indicator be in place for no longer than two days at a time, and be employed no more than once every two weeks. (Noting that the use of the busy indicator during releases doesn’t affect this.) If you need more time not participating in the review roulette, be sure to talk to your manager so they can help (which may include additional use of the busy indicator).
Merge rights
The Technical Writing team is given merge rights (through Maintainer access)
to GitLab projects as part of their role. Not all developers get Maintainer access, so Technical Writers must use this privilege responsibly.
As Maintainers, Technical Writers must limit what they merge to:
Documentation, typically in Markdown-formatted files.
UI text, error messages, and link-related updates in code files, with the approvals of appropriate engineers.
You can skip engineer approval and ask a member of the TW leadership team
or @marcel.amirault to approve code changes when:
The only code changes in a documentation MR are link fixes to match changes to documentation files or anchor names, and
The pipeline completed successfully.
Documentation-related tooling and configuration such as linters, and changes
to the gitlab-docs project. Engineers
are available for code review and merges.
In addition, Technical Writers must:
Never merge an MR with a failed pipeline.
Ensure that MRs are complete before merging, with appropriate labels and milestones.
Ensure that the DRI has reviewed and approved the MR.
Onboarding Technical Writers
While the Technical Writer is onboarding, they will be assigned to
shadow groups and then start contributing as trainees. Veteran Technical Writers will coach them through the process.
We have set up Geekbot for our twice weekly
standups (at 10:00 AM, Tuesday and Thursday, in your local timezone) and a random weekly question
(run on Wednesdays at 12:00 PM).
All members can edit and manage the standups.
To add a new member to the daily standup:
Visit the Geekbot dashboard and
sign in using your Slack account when asked.
Select the Tues/Thurs ping
standup and search the member by name in the Add participants area.
Give the newly-added member Manage access and select Save in the upper
right corner.
To add a new member to the Weekly Wednesday Question standup:
Visit the Geekbot dashboard and
sign in using your Slack account when asked.
Select the Weekly Wednesday Question
standup and search the member by name in the Add participants area.
Give the newly-added member manage access and select Save in the upper
right corner.
As a member of the Technical Writing team, you’re encouraged to add your
question to the list of random Wednesday questions! To do so:
The documentation website is refreshed every hour. On rare occasions, we might have to publish documentation
updates a little faster. If you need an urgent update, follow the steps to manually deploy the docs site.
Report a docs website problem or infrastructure issue
GitLab documentation is crafted to help users, admins, and decision-makers
learn about GitLab features and to optimally implement and use GitLab to meet
their DevOps needs.
The documentation is an essential part of the product. Its source is developed
and stored with the product in its respective paths within the
GitLab repositories.
It’s published at docs.gitlab.com (offering multiple
versions of all product documentation) and at the /help/ path on each GitLab
instance’s domain, with content for that instance’s version.
As GitLab grows, the Technical Writing team expands, and team members participate in interviews. A defined interview
process is important for a consistent hiring process.
Whether you are a contributor or a GitLab Technical Writing team member, one of your first tasks is to set up
an environment on your computer for writing and previewing GitLab documentation.
Tools for technical writers
You can use the following tools to set up your environment. Most of
these are not compulsory - you can set up your environment however you choose.
These are simply suggestions to help you get up and running quickly:
The Technical Writing Fundamentals course is available to help both GitLab and community contributors write and edit documentation for the product. This course provides direction on grammar and topic design.
This class is not required to contribute to docs.gitlab.com. Everybody can contribute!
You can review the training materials on this page, or you can take the course in Level Up.
Technical Writing Fundamentals course
The Technical Writing Fundamentals course consists of the following sections to be completed in order.
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.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
Cookie Policy
User ID: 3a7783bb-a3cf-4a9e-8838-3eee48bc7ab9
This User ID will be used as a unique identifier while storing and accessing your preferences for future.
Timestamp: --
Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.