The primary goal of the Technical Writing team is to continuously develop the GitLab product documentation to meet the evolving needs of all users and administrators.
Documentation educates readers about features and best practices, and enables them to efficiently configure, use, and troubleshoot GitLab. To this end, the team also manages the docs.gitlab.com site and related process and tooling.
Our team comprises:
Technical Writers partner with anyone in the GitLab community who is concerned with documentation, especially developers, who are typically the first to update docs for the GitLab features that they code.
If you're interested in updating or creating GitLab product documentation, see our Technical Writing Fundamentals course, which includes:
Use the private-to-GitLab #docs
Slack channel to contact the Technical Writing team. To contact the entire team
in a GitLab issue or MR, use @gl-docsteam.
GitLab provides Technical Writing Fundamentals, a course that introduces basic technical writing concepts that we follow at GitLab.
Technical Writers:
For more information on documentation at GitLab, see:
The Technical Writing team manages team-specific and general documentation-related Slack channels:
#docs: For generic GitLab documentation discussion.#docs-comments: For automated messages from Disqus comments.#docs-processes: For discussion relating to the Style Guide group and documentation processes.#docs-tooling: For discussion relating to the Test Automation Commitee,
documentation tooling, and the gitlab-docs project.#docs-site-changes: For automated messages from gitlab-docs project.#tw-team: For Technical Writing team chat.#tw-social: For Technical Writing team social chat!The Technical Writing team is broadly responsible for both developing product documentation content and helping others while they develop content, along with other tasks.
When evaluating work to meet our stakeholders' needs, we prioritize in the following order:
Documentation site (docs.gitlab.com) including maintaining and enhancing the documentation site’s:
Documentation process, including:
The Documentation Style Guide provides style recommendations 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.
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.
Collaboration, including:
Technical Writers (TWs) are assigned to and collaborate with other teams and groups as described on the DevOps stages, Development Guidelines, and other subjects sections below.
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 | Marcia Ramos | |
| Style Guide | Suzanne Selhorn | Susan Tacker |
| Testing/Vale/markdownlint | Craig Norris, Diana Logan | n/a |
| Documentation guidelines | Craig Norris | Diana Logan |
| Documentation handbook | Diana Logan | Craig Norris |
| Technical Writing handbook | Susan Tacker | Craig Norris, Diana Logan |
| Get started administering Gitlab (TAM onboarding) | Lyn Landon | Kati Paizee |
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.The Technical Writer assigned to Development Guidelines is Marcia Ramos. For regular merge request reviews:
Each Technical Writer has an assigned backup Technical Writer that’s listed in the DevOps Stages and Groups assignment table.
Although the usual role of a backup Technical Writer is to provide coverage for primary writers who may be out of the office, the backup can also be a resource for a stage/group's normal Technical Writer. For example, depending on their bandwidth, the backup may be able to help with coverage if the primary Technical Writer gets too busy (for example, if the primary writer also has release post duty).
Technical Writers should ensure that their out-of-office messaging reflects their backup, and should communicate with their PMs and developers to introduce their backup Technical Writer.
Whenever you’re communicating with a backup Technical Writer to ask for an issue's status or their assistance with a technical writing issue, please 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.
If neither the primary or backup Technical Writer are available to help, you can post in the #docs channel to ask for general assistance for your issue.
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:
See how to participate in the hiring process for Technical Writers.
While the Technical Writer is onboarding, they will be assigned to shadow groups and then start contributing as trainees, as described below. Veteran Technical Writers will coach them through the process.
For the first release cycle that begins after the new member start
date, they will shadow (read) their buddy's work in their most active
Stage Group, plus one other stage group/writer decided with the
tech writing manager and the team. 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, and answering questions.
For the second release cycle that begins after the new member's start date, unless the tech writing manager extends the shadowing phase, 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 as of the next release. The veteran Technical Writer who is assigned to that Group will assign substantial parts of the work to the new member for this group, 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; a few minor doc improvement projects/fixes.
For the third release cycle, the onboarding tech 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.
Technical Writers are assigned merge requests to review 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:
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:
See:
While we welcome improvements to documentation from the community, we also encourage people to contribute to the development of our product documentation website, at https://docs.gitlab.com.
If you'd like to help us further improve our documentation site, here are some resources:
