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.
The backup writer is assigned to cover merge request reviews and urgent matters for the designated tech writer when they are out (vacations, sickness, and any other temporary leave). They can also naturally pair to work together on complex issues when needed.
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:
| Subject | Assigned Technical Writer/DRI | Backup/Team members |
|---|---|---|
| Development guidelines | Suzanne Selhorn | |
| Style Guide | Suzanne Selhorn | Susan Tacker |
| Testing/Vale/markdownlint | Diana Logan | n/a |
| Documentation handbook | Diana Logan | Suzanne Selhorn |
| Technical Writing handbook | Susan Tacker | Diana Logan |
| Get started administering GitLab (TAM onboarding) | Lyn Landon | Kati Paizee |
| Tutorials | Kati Paizee | |
| GitLab Development Kit (GDK) | Axil, Evan Read, Marcel Amirault |
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:
Each Technical Writer has a backup Technical Writer available to them for their DevOps Stages and Groups assignments.
Backup Technical Writers can be used to provide coverage for out-of-office Technical Writers, and can also be a resource for a stage/group's normal Technical Writer. For example, depending upon availability, the backup may provide coverage if the primary Technical Writer gets too busy (for example, if they have release post duty).
To ensure coverage, Technical Writers should use the following process for each assigned group whenever preparing to be out of the office:
Communicate to the PM/EM the mechanism to use for assistance with new content or documentation reviews during the Technical Writer's absence. Depending on the Technical Writer, requests can go to a backup Technical Writer (set up in advance) or to the #docs channel for an available Technical Writer.
Send a message in the group's Slack channel indicating the agreed upon method.
Copy the link to the message into the #docs channel.
Technical Writers should ensure their out-of-office messaging reflects the selected mechanism to use for coverage.
Whenever you’re communicating with a backup or alternate Technical Writer to ask for an issue's status or their assistance with a technical writing issue, be aware that they may require additional context, and that your request will need to be incorporated into the list of stage/group and feature priorities for their primary responsibility.
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: