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 @gl-docsteam.
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 gitlab-docs project.#docs-site-changes: Automated messages from gitlab-docs project.#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:
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.
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:
As GitLab grows, it's important to keep high-quality documentation, and 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 Dev 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 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/engineering/ux/technical-writing/#technical-writer-pto for ways to get help.
For urgent _named time-sensitve task_ matters, ping _named TW_.
When a Technical Writer is on PTO, the rest of the team will do periodic queue checks to ensure work isn't inadvertently blocked by them.
The team should check Reviewer Roulette regularly and see which TW team members are OOO, based on their reported GitLab status. If an OOO TW team member has assigned MRs waiting for review, another team member should ensure the MRs can be reviewed in a timely manner by either:
Along with Technical Writers' normally assigned work, there are recurring tasks that need to be regularly completed:
technical-writing repository to track maintenance work (using the tw-monthly-tasks template). 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 following principles guide Technical Writers when conducting technical writing reviews:
To balance velocity and quality, the writers use this workflow:
When a developer opens a merge request, they are the DRI for the code in that MR. Writers should use caution if they work in a developer branch that contains code, and should get explicit approval before doing so. Pushing to a branch can cause hard-to-resolve merge conflicts, and content can be accidentally overwritten.
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 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 #tw-onboarding-<groupname>
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:
See: