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 and related epic drive 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 to better organize the documentation content, improve the information architecture, and upgrade the search capabilities. These larger projects, completed in addition to feature documentation, provide continual, iterative improvement to the user experience of our 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 @gl-docsteam.
The team manages general documentation-related and team-specific Slack channels:
#docs: Questions and general discussion about GitLab documentation, and requests by GitLab team members for doc and UI text reviews.#docs-processes: Discussion about documentation processes.#docs-tooling: Discussion about documentation tooling and the gitlab-docs project.#docs-site-changes: Automated messages from gitlab-docs project.#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:
lint-doc.shAny 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 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.
Technical Writers (TWs) collaborate with other teams and groups as described on the DevOps stages, Development Guidelines, and other subjects sections below.
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
that has 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.
Not sure who's responsible for a feature? Review feature assignments by stage or group.
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:
The Technical Writing team gets assistance with the gitlab-docs project from stable counterparts outside the team.
| Subject | Person |
|---|---|
| Backend reviews | Ash McKenzie, David O'Regan |
| Frontend reviews | Lukas 'Eipi' Eipert, David O'Regan |
As GitLab grows, it's important to ensure that the guidelines for contributors are consistent and aligned throughout the organization. Development guidelines consist of:
/development directory.contents
must be reviewed and approved by the TW assigned to Development Guidelines.For merge request reviews:
The technical writing team supports a large amount of content.
The number of pages in the five primary repositories (GitLab, Omnibus, Charts, Operator, and Runner):
| Date | # of pages |
|---|---|
| May 2020 | 1,165 |
| Jan 2022 | 1,562 |
| June 2022 | 1,633 |
| Sept 2022 | 1,785 |
| Dec 2022 | 1,840 |
| Mar 2023. | 1,929 |
Change between May 2020 and Mar 2022: 764 more pages (a 65% increase)
The number of words in these repositories:
| Date | Word count |
|---|---|
| May 2020 | 1,190,371 |
| Jan 2022 | 2,017,183 |
| June 2022 | 2,166,052 |
| Oct 2022 | 2,271,350 |
| Dec 2022 | 2,397,335 |
| Mar 2023 | 2,546,466 |
Change between May 2020 and Mar 2023: 1,356,095 more words
The word count has more than doubled in this timeframe.
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:
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.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 use the following levels of edit:
Light
Medium
Heavy
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:
architecture/blueprints directory)development directory)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-docs project. 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 more information about onboarding phases and tasks, see the Technical Writer onboarding template.
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:
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:
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.