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.
Use the #docs Slack channel to contact the technical writing team. It's a private-to-GitLab channel.
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 Committee 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 team is broadly responsible for the following areas at GitLab.
Documentation Site (docs.gitlab.com) including maintaining and enhancing the documentation site’s:
Documentation Process, including:
The Style Committee includes multiple members of the Technical Writing team, with one DRI and a rotating set of additional members. The committee works with the entire Technical Writing team, who are always welcome to raise style issues or MRs and engage in style-related discussions in GitLab or Slack.
This committee is responsible for:
Responsibilities:
~tw-style label.#docs-processes Slack channel and help with style questions.Committee roles:
For current membership, see Assignments to other projects and subjects.
The Test Automation Committee covers:
lint-doc.sh, which includes checking file permissions and preventing new README.md files.Responsibilities:
~tw-testing label.#docs-tooling Slack channel and help with testing questions.Committee roles:
~tw-testing, triages issues, and helps ensure issues/MRs move to resolution.For current membership, see Assignments to other projects and subjects.
Collaboration, including:
This work is sorted into the top-level Documentation epics linked above.
Technical writers (aka "TWs" or "docs team members") 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.
Not sure what group a feature falls into? Search the product categories.
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 | Backup |
|---|---|---|
| Documentation guidelines (a subset of the Development Guidelines | Mike Lewis | Craig Norris |
| Documentation handbook | Craig Norris | Mike Lewis |
| Technical Writing handbook | Susan Tacker | Craig Norris |
| Development guidelines (see the section below) | Marcia Ramos | Mike Jang |
| Style Committee DRI | Mike Lewis | |
| Style Committee members | Marcia Ramos, Mike Jang, Suzanne Selhorn | |
| Test Automation Committee DRI | Marcel Amirault | |
| Test Automation Committee Vale DRI | Amy Qualls | |
| Test Automation Committee members | Evan Read | |
| Subscriptions | TBA | TBA |
| GitLab Docs | SSE Team | — |
| GitLab Development Kit (GDK) | Evan Read | TBA |
| GitLab Pages Daemon | TBA | TBA |
| GitLab Pages Examples | Axil | TBA |
The Technical Writer (TW) assigned to Development Guidelines (SME) is Marcia Ramos and her backup TW is Mike Jang. 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:
gitlab/doc/development/* must be reviewed and approved by the TW assigned to Dev Guidelines, with the exception of the Documentation Style Guide which is maintained by the Techncial Writing Style Committee.contents
must be reviewed and approved by the TW assigned to Dev Guidelines.For Development Guidelines that may be established in other projects, the assigned TW will help upon request. If a larger project is created with ongoing development, the TW for Dev Guidelines and TW Manager will evaluate with the engineers the necessity of regular reviews.
For content changes specifically related to a particular stage group, the TW assigned to that group can perform the review and then assign the MR to the TW assigned Dev Guidelines for approval/merge.
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 (such as 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-team 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:
Docs project log checking: The docs project has jobs in the CI/CD pipeline logs that report fixable issues. These jobs are allowed to silently fail to avoid having minor failures prevent the site's deployment. The Technical Writer with this task should check the following logs regularly, and if needed, create MRs to fix reported failures or create issues for significant reported problems:
test_external_links manual job in the most recently run
Scheduled pipeline.compile_prod or compile_dev. In the provided job log,
search for kramdown warning messages, which are usually caused by
problematic HTML or square brackets.Current schedule of regular Technical Writing tasks:
| Month | Release Post | Log checking |
|---|---|---|
| Jan 2020 | 12.7 - Marcia Ramos | n/a |
| Feb 2020 | 12.8 - Marcin Sędłak-Jakubowski | n/a |
| Mar 2020 | 12.9 - Axil | n/a |
| Apr 2020 | 12.10 - Russell Dickenson | n/a |
| May 2020 | 13.0 - Mike Jang | n/a |
| Jun 2020 | 13.1 - Amy Qualls | n/a |
| Jul 2020 | 13.2 - Suzanne Selhorn | n/a |
| Aug 2020 | 13.3 - Nick Gaskill | Marcin Sędłak-Jakubowski |
| Sep 2020 | 13.4 - Marcel Amirault | Axil |
| Oct 2020 | 13.5 - Mike Lewis | Russell Dickenson |
| Nov 2020 | 13.6 - Evan Read | Mike Jang |
| Dec 2020 | 13.7 - Marcia Ramos | Amy Qualls |
Note: Be sure to keep the Release Post column in sync with the Release Post Scheduling page.
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.
To consult the current assignments, see the onboarding technical writers spreadsheet.
Group shadowing
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.
Group trainees
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.
Group coaching
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 for merge request reviews (of both team members and community contributors) according to the stage groups they are assigned.
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.In addition, before merging such MRs, technical writers should:
See:
