Technical Writing Team

About Us

The primary goal of the Technical Writing team is to continuously develop GitLab's product documentation content to meet the evolving needs of all users and administrators.

Documentation is intended to educate readers about features and best practices, and to enable 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:

A technical writing manager.
A group of technical writers.

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.

The technical writing team Slack channel is #docs-team and technical writers are also active in the larger #docs channel (both private to GitLab Inc.).

Projects

Technical writers:

Act as maintainers of documentation for many engineering projects.
Frequently act as authors or reviewers of the documentation in collaboration with others in the GitLab community.
Are assigned to specific DevOps stage groups.

For more information on documentation at GitLab, see:

The Documentation section of the Handbook.
GitLab Documentation guidelines in the contributor documentation.

Responsibilities

The team is broadly responsible for the following at GitLab.

Content

Documentation content, including:
- Developing new content to meet the needs of the community.
- Reviewing and collaborating on documentation plans, reviewing doc merge requests or recently merged docs, and ensuring that content meets style and language standards.
- Reorganizing, revamping, and authoring improved content to ensure completeness and a smooth user experience.
UI content
- Collaborating with Product Designers on and review of various forms of UI text, such as microcopy, links from the UI to documentation, error messages, UI element labels, etc.

Publishing

Documentation Site (docs.gitlab.com) including maintaining and enhancing the documentation site’s:

Architecture
Design
Automation
Versioning
Search
SEO
Feedback methods
Analytics

Processes

Documentation Process, including:

Ensuring that processes are in place and being followed to keep the GitLab docs up to date.
Following and optimizing documentation workflows with Product and Engineering, Documentation Team workflows, and the division of work.
Triaging doc-related issues.
Refining the Documentation Style Guide and continuously improving content about GitLab documentation and its contribution process.
Making it easier for anyone to contribute to the documentation while efficiently handling community contributions to docs.

Collaboration

Collaboration, including:

Working on documentation efforts with Product, Support, Marketing, Engineering, Community Marketing, other GitLab teams, and the wider GitLab community.
Ensuring that relevant documentation is easily accessible from within the product.
Acting as reviewers of the monthly release post.

This work is sorted into the top-level Documentation epics linked above.

Assignments

Technical writers (aka "TWs" or "docs team") are assigned to and collaborate with other teams and groups as described in the DevOps stages and other subjects according to the tables below.

Designated technical writers

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 the end-user, and generally partner with subject-matter experts 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 that there are some planned changes to these assignments.

Section	Stage	Group	Technical writer	Backup
Dev	Manage	Access	Mike Jang	---
Dev	Manage	Compliance	Mike Jang	---
Dev	Manage	Import	Mike Jang	---
Dev	Manage	Analytics	Mike Jang	---
Dev	Manage	Spaces	Mike Jang	---
Dev	Plan	Project Management	Marcin Sędłak-Jakubowski	---
Dev	Plan	Portfolio Management	Marcin Sędłak-Jakubowski	---
Dev	Plan	Certify	Marcin Sędłak-Jakubowski	---
Dev	Create	Source Code	Marcia Ramos	---
Dev	Create	Knowledge	Marcia Ramos	---
Dev	Create	Static Site Editor	Marcia Ramos	---
Dev	Create	Editor	Marcia Ramos	---
Dev	Create	Gitaly	Axil	---
Dev	Create	Gitter	Axil	---
CI/CD	Verify	Continuous Integration	Marcel Amirault	---
CI/CD	Verify	Runner	Marcel Amirault	---
CI/CD	Verify	Testing	Marcel Amirault	---
CI/CD	Package	Package	Axil	---
Secure	Secure	Static Analysis	Nick Gaskill	---
Secure	Secure	Dynamic Analysis	Nick Gaskill	---
Secure	Secure	Composition Analysis	Nick Gaskill	---
Secure	Secure	Attack Surface	Nick Gaskill	---
CI/CD	Release	Progressive Delivery	Marcia Ramos	---
CI/CD	Release	Release Management	Marcia Ramos	---
Ops	Configure	Orchestration	Evan Read	---
Ops	Configure	System	Evan Read	---
Ops	Monitor	APM	Axil	---
Ops	Monitor	Health	Axil	---
Defend	Defend	Runtime Application Security	Axil	---
Defend	Defend	Threat Management	Axil	---
Defend	Defend	Application Infrastructure Security	Axil	---
Defend	Defend	Anomaly Detection	Axil	---
Growth	Growth	Acquisition	Russell Dickenson	---
Growth	Growth	Conversion	Russell Dickenson	---
Growth	Growth	Expansion	Russell Dickenson	---
Growth	Growth	Retention	Russell Dickenson	---
Growth	Growth	Fulfillment	Russell Dickenson	---
Growth	Growth	Telemetry	Russell Dickenson	---
Enablement	Enablement	Distribution	Axil	---
Enablement	Enablement	Geo	Evan Read	---
Enablement	Enablement	Memory	Russell Dickenson	---
Enablement	Enablement	Ecosystem	Russell Dickenson	---
Enablement	Enablement	Search	Russell Dickenson	---
Enablement	Enablement	Database	---	---
Enablement	Enablement	Contributor Experience	---	---

Assignments to other projects and subjects

For collaboration in other projects and subjects:

Subject	Technical writer	Backup
Development guidelines (1)	Marcia Ramos	TBA
Subscriptions	TBA	TBA
GitLab Docs - frontend	Marcia Ramos	TBA
GitLab Docs - backend	Axil	TBA
GitLab Omnibus	Axil	TBA
GitLab Charts	Axil	TBA
GitLab Runner	Marcel Amirault	Evan Read
GitLab Development Kit (GDK)	Evan Read	TBA
GitLab Pages Daemon	TBA	TBA
GitLab Pages Examples	Axil	TBA
Applications/Partners	Marcia Ramos	TBA
Technical writing handbook	Mike Lewis
Other	Mike Lewis

(1) Note: Development guidelines refer to the docs under gitlab/doc/development/*. If the changes to this section introduced in an MR are specifically related to a stage group, the technical writer assigned to that group should perform the review and CC @marcia for her information.

Onboarding 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.

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.

Reviews

Technical writers are assigned for merge request reviews (of both team members and community contributors) according to the stage groups they are assigned.

Documentation process

See:

Technical Writing workflow in the handbook.
Documentation workflows in the contributor documentation.

FY20 Vision

New Content Development - Leading the planning and authoring of new content to better meet user needs. This will be a significantly increased proportion of the team’s work, and will make use of improved methods and standards.
- Authoring docs that better address use cases with A-to-Z process flows, going beyond existing feature references and procedures that can be difficult to adapt to real-world use cases. Supported by updated standards for content types and structure.
- Getting Started - a.k.a. unboxing or onboarding docs for various audiences and scenarios.
Content Improvement:
- Revamping existing content pages/sections, so that they meet our latest standards, including contextual information on every page (what, why, who).
- Improve use of documentation feedback/sensing mechanisms. Improved sourcing and channeling/triage; making use of existing comments and issues, while bringing in new sources including search data, surveys, user testing, etc.
- Improve rate of contributions to docs as SSOT and using ‘docs-first’ methods by tracking contributions and demonstrating best practices.
Docs UX:
- Next iteration of docs versioning.
- Removing documentation from /help, linking instead from UI to versioned links on docs.gitlab.com.