The GitLab Technical Writing team collaborates with developers, product managers, and the community to develop product documentation.
Good documentation meets the evolving needs of all 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 website. For example, we know that people have trouble finding information on docs.gitlab.com. We have roadmap items to better organize the documentation content, improve the information architecure, and upgrade the search capabilities. These larger projects, completed in addition to feature documentation, provide continual, iterative improvement to the user experience of the documentation.
Anyone can contribute to the documentation. Follow our GitLab documentation guidelines.
The Technical Writing team includes:
To contact the entire team in a GitLab issue or MR, use
The team manages general documentation-related and team-specific Slack channels:
#docs: Generic GitLab documentation discussion.
#docs-processes: Discussion relating to the Style Guide group and documentation processes.
#docs-tooling: Discussion relating to the Test Automation Commitee, documentation tooling, and the
#docs-site-changes: Automated messages from
#docs-comments: Automated messages from Disqus comments.
#tw-team: Technical Writing team chat.
#tw-social: Technical Writing team social chat.
If you're interested in updating or creating GitLab product documentation, see our Technical Writing Fundamentals course, which includes:
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:
When evaluating work to meet our stakeholders' needs, we prioritize in the following order:
The team is responsible for developing and maintaining efficient processes, including:
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:
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.
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 Manage stage Category Direction page on Internationalization. For a step-by-step guide to translation contributions, read Translating GitLab.
If you were directed here from a documentation page's metadata: References to stages and groups in documentation metadata don't indicate developer group ownership, but instead help connect people to the assigned stable counterpart technical writer with subject matter awareness. If internal groups want to use other metadata parameters to track information in documentation pages, please create an issue in the Technical Writing repository for discussion. Additional discussions are in this issue.
The designated Technical Writer is the go-to person for their assigned stage groups. They collaborate with other team members to plan new documentation, edit existing documentation, review any proposed changes to documentation, suggest changes to the microcopy exposed to users, and generally partner with subject matter experts (SMEs) in all situations where documentation is required.
When a Technical Writer is on PTO, the whole team acts as their backup.
Note: If you've been directed here from metadata in a documentation page
none as the stage, refer to the
Assignments to other projects and subjects
section, referencing the group shown in metadata with the listed Subjects in the table.
|Section||Stage||Group||Assigned technical writer|
|Analytics||Analytics||Product Intelligence||Clayton Cornell|
|Analytics||Analytics||Product Analytics||Clayton Cornell|
|Data-science||ModelOps||Applied Machine Learning||#docs Slack channel|
|Data-science||ModelOps||MLOps||#docs Slack channel|
|Data-science||ModelOps||DataOps||#docs Slack channel|
|Dev||Manage||Authentication & Authorization||Evan Read|
|Dev||Plan||Project Management||Marcin Sędłak-Jakubowski|
|Dev||Plan||Product Planning||Marcin Sędłak-Jakubowski|
|Dev||Create||Source Code||Amy Qualls|
|Dev||Create||Code Review||Amy Qualls|
|Enablement||Data Stores||Application Performance||Suzanne Selhorn|
|Enablement||Data Stores||Global Search||Ashraf Khamis|
|Enablement||Data Stores||Database||Amy Qualls|
|Enablement||Data Stores||Pods||Suzanne Selhorn|
|Fulfillment||Fulfillment||Fulfillment Platform||Fiona Neill|
|Fulfillment||Fulfillment||Billing and Subscription Management||Fiona Neill|
|Fulfillment||Fulfillment||Commerce Integrations||Fiona Neill|
|Ops||Verify||Pipeline Execution||Marcel Amirault|
|Ops||Verify||Pipeline Authoring||Marcel Amirault|
|Ops||Verify||Pipeline Insights||Marcel Amirault|
|Platforms||SaaS Platforms||Delivery||#docs Slack channel|
|Platforms||SaaS Platforms||Scalability||#docs Slack channel|
|Platforms||SaaS Platforms||GitLab Dedicated||#docs Slack channel|
|Platforms||SaaS Platforms||US Public Sector Services||#docs Slack channel|
|Sec||Secure||Static Analysis||Russell Dickenson|
|Sec||Secure||Dynamic Analysis||Russell Dickenson|
|Sec||Secure||Composition Analysis||Russell Dickenson|
|Sec||Secure||Vulnerability Research||Clayton Cornell|
|Sec||Govern||Security Policies||Clayton Cornell|
|Sec||Govern||Threat Insights||Clayton Cornell|
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.
For collaboration in other projects and subjects:
|Subject||Assigned technical writer|
|Development guidelines||Suzanne Selhorn|
|Style Guide||Suzanne Selhorn|
|Documentation handbook||Diana Logan|
|Technical Writing handbook||Susan Tacker|
|Get started administering GitLab (TAM onboarding)||Lyn Landon|
|What's new||Kati Paizee|
|GitLab Development Kit (GDK)||Axil, Evan Read, Marcel Amirault, Kati Paizee, Fiona Neill|
As GitLab grows, it's important to ensure that the guidelines for contributors are consistent and aligned throughout the organization. Development guidelines consist of:
contentsmust be reviewed and approved by the TW assigned to Development Guidelines.
For merge request reviews:
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:
If taking extended PTO (more than one week), Technical Writer should consider using the Technical Writer coverage issue. This issue can describe exactly who is providing coverage, for what, and by what means.
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:
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://about.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_.
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:
Along with Technical Writers' normally assigned work, there are recurring tasks that need to be regularly completed:
technical-writingrepository to track maintenance work (using the
tw-monthly-taskstemplate). If additional work beyond what's described in the maintenance issue is required, the Technical Writer creates merge requests and additional issues as needed.
Schedule for Docs project maintenance tasks:
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.
The Technical Writers edit the documentation based on the following levels of edit:
To balance quality, speed, and resource constraints, the technical writers apply different levels of edit to different documentation.
These guidelines are meant to provide general guidance. They aren't set in stone, and they can be overridden on a case-by-case basis.
These items receive a light edit:
These items receive a medium edit:
These items receive a heavy edit:
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.
To balance velocity and quality, the writers use this workflow:
When a writer opens a merge request, another writer must review and merge. Peer reviews are important to maintain quality and help the team build a common voice.
When anyone else (like a developer, community member, or Support team member) opens a merge request:
If the MR contains documentation and code, the writer adds suggestions but does not merge. The MR is merged by another developer.
If the MR contains documentation only:
When a bot or a community contributor mentions either
@gl-docsteam or several Technical Writers based on CODEOWNERS, TWs should volunteer to:
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.
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.
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 preceeding the 22nd of the month, 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).
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. Technical writers should use this privilege responsibly.
As Maintainers, Technical Writers should limit what they merge to:
gitlab-docsproject. Engineers in the Editor team are available for code review and merges.
In addition, Technical Writers should:
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.
For the first release cycle that begins after the new member starts at GitLab, they will shadow (read) their buddy's work in their most active
stage group, plus one other stage group/writer (decided with the
Technical Writing Manager). Veteran Technical Writers will
proactively share relevant issues, merge requests, and communications
with their shadows by using a
Slack channel, creating it if it doesn't already exist.
For the second release cycle that begins after the new member's start, unless the shadowing phase is extended, they will act as a trainee on one or more groups as assigned by the Manager. The intent is to take on the group as its Technical Writer for the next release. The veteran Technical Writer who is assigned to that Group will assign substantial parts of the work to the new member, which accounts to roughly half of the groups's reviews of MRs with docs, UI text, and release post content; a small but substantial documentation authoring project; and a few minor doc improvement projects/fixes.
For the third release cycle, the onboarding Technical Writer assumes the full role of Technical Writer for their assigned group, except that they will not yet have merge rights. The former TW assigned to the group is now the coach, who will review all their work (including reviews they perform of other authors) before merging it or approving it for another maintainer to merge. They may share the burden of these reviews with other Technical Writers.
We have set up Geekbot for our daily standups (at 10:00 AM, 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:
To add a new member to the Weekly Wednesday Question standup:
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:
We welcome improvements to content as well as to the development of our documentation website, at https://docs.gitlab.com.
For more information about community contributions, see:
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.