Technical Writing

The GitLab Technical Writing team collaborates with developers, product managers, and the community to develop product documentation.

Good documentation meets the evolving needs of 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 documentation website. For example, we know that people have trouble finding information on docs.gitlab.com. We have roadmap items and OKRs to replatform the docs site, provide better task-based information, and make content easier to find. These larger projects, completed in addition to feature documentation, provide continual, iterative improvement to the user experience of our documentation.

Anyone can contribute to the documentation. Follow our GitLab documentation guidelines.

About Us

The Technical Writing team includes:

Contact Us

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: Questions and general discussion about GitLab documentation, and requests by GitLab team members for doc and UI text reviews.
  • #docs-processes: Discussion about documentation processes.
  • #docs-tooling: Discussion about documentation tooling and the gitlab-docs project.
  • #docs-site-changes: Automated messages from gitlab-docs project.
  • #tw-team: Technical Writing team chat.
  • #tw-social: Technical Writing team social chat.

Public Training for GitLab Technical Writing

If you’re interested in updating or creating GitLab product documentation, see our Technical Writing Fundamentals course, which includes:

  • Guidelines for technical writing.
  • GitLab style conventions.
  • Information about internal testing.
  • Instructions for content types.

Responsibilities

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:

  • Maintaining documentation for many engineering projects.
  • Occasionally 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 documentation to ensure completeness and a smooth user experience.
  • Collaborating with Product Designers on UI text, such as microcopy, links from the UI to documentation, error messages, and UI element labels.
  • Acting as Technical Writing Lead for the monthly release post.

Prioritization

When evaluating work to meet our stakeholders’ needs, we prioritize in the following order:

  1. Feature work (including documenting new features, and providing guidance on UI text)
  2. OKR-related work
  3. Backlog issues (including docs technical debt and implementing content topic design)
  4. All other tasks (including creating suggestion- or warning-level Vale rules)

Processes

The team is responsible for developing and maintaining efficient processes, 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.

Style Guide

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:

Testing

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:

  • Text content and writing style: markdownlint, Vale
  • Text formatting: markdownlint, yamllint
  • Link validity: Nanoc
  • File permissions and naming: lint-doc.sh

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

Translation and internationalization

Everyone can contribute to the translation of GitLab from English into other languages. To learn more about translation and internationalization at GitLab, visit the Import and Integrate direction page and Manage stage Category Direction page on Internationalization. For a step-by-step guide to translation contributions, read Translating GitLab.

The docs.gitlab.com site is not included in the community efforts to internationalize GitLab. Discussion on translating documentation into other languages is included in this issue.

Assignments

Technical Writers (TWs) collaborate with their assigned groups. TWs can also be assigned other work.

Some content on docs.gitlab.com is not reviewed by TWs.

Assignments to DevOps Stages and Groups

The designated Technical Writer is the go-to person for their assigned groups. They collaborate with other team members to plan new documentation, edit existing documentation, review any proposed changes to documentation, suggest changes to UI microcopy, and generally partner with subject matter experts (SMEs) in all situations where documentation is required.

Section Stage Group Assigned technical writer
Analytics Monitor Analytics Instrumentation Slack Logo #docs Slack channel
Analytics Monitor Observability Slack Logo #docs Slack channel
Analytics Monitor Product Analytics
Analytics Monitor Respond Slack Logo #docs Slack channel
CD Deploy Environments
CI Package Container Registry
CI Package Package Registry
CI Verify Hosted Runners
CI Verify Pipeline Authoring
CI Verify Pipeline Execution
CI Verify Pipeline Security
CI Verify Runner
Core Platform Data Stores Database Slack Logo #docs Slack channel
Core Platform Data Stores Global Search
Core Platform Data Stores Tenant Scale
Core Platform Manage Foundations
Core Platform Manage Import and Integrate
Core Platform Systems Cloud Connector
Core Platform Systems Distribution::Build
Core Platform Systems Distribution::Deploy
Core Platform Systems Geo
Core Platform Systems Gitaly::Cluster
Core Platform Systems Gitaly::Git
Data Science AI-powered AI Framework
Data Science AI-powered AI Model Validation
Data Science AI-powered Custom Models
Data Science AI-powered Duo Chat
Data Science ModelOps DataOps
Data Science ModelOps MLOps
Dev Create Code Creation
Dev Create Code Review
Dev Create Editor Extensions
Dev Create IDE
Dev Create Source Code
Dev Plan Knowledge Slack Logo #docs Slack channel
Dev Plan Optimize
Dev Plan Product Planning
Dev Plan Project Management
Fulfillment Fulfillment Fulfillment Platform Slack Logo #docs Slack channel
Fulfillment Fulfillment Provision
Fulfillment Fulfillment Subscription Management Slack Logo #docs Slack channel
Fulfillment Fulfillment Utilization
Growth Growth Acquisition Slack Logo #docs Slack channel
Growth Growth Activation Slack Logo #docs Slack channel
SaaS Platforms SaaS Platforms GitLab Dedicated
SaaS Platforms SaaS Platforms Delivery Slack Logo #docs Slack channel
SaaS Platforms SaaS Platforms US Public Sector Services Slack Logo #docs Slack channel
SaaS Platforms SaaS Platforms Scalability Slack Logo #docs Slack channel
SaaS Platforms SaaS Platforms Switchboard
Sec Govern Anti-Abuse
Sec Govern Authentication
Sec Govern Authorization
Sec Govern Compliance
Sec Govern Security Policies
Sec Govern Threat Insights
Sec Secure Composition Analysis
Sec Secure Dynamic Analysis
Sec Secure Secret Detection
Sec Secure Static Analysis
Sec Secure Vulnerability Research Slack Logo #docs Slack channel
Single-Engineer Groups Deploy Five Minute Production App Slack Logo #docs Slack channel
Single-Engineer Groups Mobile Mobile DevOps Slack Logo #docs Slack channel

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.

When a Technical Writer is on PTO, the whole team acts as their backup.

Assignments to other projects and subjects

For collaboration in other projects and subjects:

Subject Assigned technical writer
The documentation site Susan TackerSusan Tacker
The documentation site backend (code, automation) Sarah GermanSarah German
GitLab Design System (“Pajamas”) information under content Suzanne SelhornSuzanne Selhorn
Style Guide Suzanne SelhornSuzanne Selhorn
Testing/Vale/markdownlint Diana LoganDiana Logan
Documentation handbook Diana LoganDiana Logan
Technical Writing handbook Susan TackerSusan Tacker
Tutorials Kati PaizeeKati Paizee
What’s new Kati PaizeeKati Paizee
GitLab Development Kit (GDK) Ashraf KhamisAshraf Khamis , Achilleas PipinellisAchilleas Pipinellis , Evan ReadEvan Read , Fiona NeillFiona Neill , Jon GlassmanJon Glassman , Lorena CiutacuLorena Ciutacu , Marcel AmiraultMarcel Amirault , Phillip WellsPhillip Wells , Russell DickensonRussell Dickenson

Content not reviewed by TWs

Technical writers do not review content in:

  • The doc/architecture directory. Any Maintainer can merge docs in this directory, though a review from a coach engineer might be needed.
  • The doc/development directory. Any Maintainer can merge docs in the doc/development directory. The only exception is /doc/development/documentation, where the writers maintain guidelines.
  • The doc/solutions directory. This information is created, reviewed, merged, and maintained by Solutions Architects.

Stable counterparts

The Technical Writing team gets assistance with the gitlab-docs project from stable counterparts outside the team.

Subject Person
Backend reviews Ash McKenzie, David O’Regan
Frontend reviews Lukas ‘Eipi’ Eipert, David O’Regan
Support Mike Lockhart

Docs site stats

The technical writing team supports a large amount of content.

The number of pages in the five primary repositories (GitLab, Omnibus, Charts, Operator, and Runner):

Date # of pages Increase from previous quarter
Mar 2024 2,308 5 %
Dec 2023 2,201 5 %
Sept 2023 2,088 8 %
Jun 2023 1,993 5 %
Mar 2023 1,929 3 %
Dec 2022 1,840 -
Sept 2022 1,785 -
June 2022 1,633 -
Jan 2022 1,562 -
May 2020 1,165 -

Change between May 2020 and Mar 2024: 1,143 more pages (a 98% increase)

The number of words in these repositories:

Date Word count Increase from previous quarter
Mar 2024 3,183,647 6 %
Dec 2023 2,990,400 5 %
Sept 2023 2,842,399 5 %
Jun 2023 2,701,888 6 %
Mar 2023 2,546,466 6 %
Dec 2022 2,397,335 -
Oct 2022 2,271,350 -
June 2022 2,166,052 -
Jan 2022 2,017,183 -
May 2020 1,190,371 -

Change between May 2020 and Mar 2024: 1,993,276 more words (a 167% increase)

The word count has more than doubled in this timeframe.

Analytics

GitLab Team Members can view docs site metrics on the docs.gitlab.com LookerStudio dashboard. To view page level analytics, select Page views by month, and add the page URL in the value field. Do not include https:// as part of the value.

To make or suggest changes to the dashboard, open an issue in the Marketing Strategy and Analytics project.

Technical Writer PTO

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:

  • Reviewer Roulette. A rouletted Technical Writer can be pinged or assigned to an issue or merge request.
  • A request in the #docs channel in Slack, where it will be picked up by an available volunteer Technical Writer.
  • For help with a specific, time-sensitive, in-progress piece of work, a pre-arranged Technical Writer. The Technical Writer can be pinged on issues or merge requests and begin participating.

If taking extended PTO (more than one week), Technical Writer should consider using the Technical Writer coverage issue. This issue can describe exactly who is providing coverage, for what, and by what means.

Taking PTO

When taking PTO, Technical Writers:

  1. 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:

    • Reviewer Roulette can make accurate suggestions.
    • The TW team can easily see the PTO status of all team members when checking the Roulette dashboard.
  2. Send a message in the group Slack channels indicating where to find the available mechanisms. For example:

    1
    2
    3
    
    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/product/ux/technical-writing/#technical-writer-pto for ways to get help.
    For urgent _named time-sensitive task_ matters, ping _named TW_.
    

Merge request queue checks

Before a Technical Writer goes on PTO, the writer or their manager should determine who will check the writer’s MR queue. The assigned person should check the queue at least once each day in the GitLab Review Workload Dashboard.

The assigned writer does not need to do the work. When they check the queue, they can:

  • Assign the MRs to themselves for review.
  • Use Roulette to find other TWs to review.

Regularly scheduled tasks

Along with Technical Writers’ normally assigned work, there are recurring tasks that need to be regularly completed:

  • Release Post Structural Check: The Technical Writing Lead reviews the content for the release post published at the end of each milestone. See the Release Post Scheduling Handbook page for each milestone’s assigned writer.
  • Monthly doc version: At the end of each milestone, a Technical Writer creates the monthly version for the docs site. The Technical Writer assigned to this task is the writer who completed the release post structural check for the previous milestone.
  • Docs project maintenance tasks: Each month, one Technical Writer is assigned to complete maintenance tasks for the documentation site and its content. This involves creating a new issue using the tw-monthly-tasks template in the technical-writing project to track maintenance work. 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:

Reviews

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.

Levels of edit

The Technical Writers use the following levels of edit:

Light

  • Ensure the pipeline passes and no obvious grammar, spelling, or punctuation errors exist.

Medium

  • Ensure the pipeline passes and no grammar, spelling, or punctuation errors exist.
  • Ensure the content is clear, discoverable, navigable, and written with the user’s perspective in mind.
  • Ensure the content meets the guidelines in the Documentation Style Guide.

Heavy

  • Ensure the pipeline passes and no grammar, spelling, or punctuation errors exist.
  • Ensure the content is clear, discoverable, navigable, and written with the user’s perspective in mind.
  • Ensure the content meets the guidelines in the Documentation Style Guide.
  • Ensure the content conforms to the defined topic types.
  • Ensure the content fits well into the larger documentation set and does not duplicate information in other areas.
  • For UI text, ensure the content meets the standards defined in the Pajamas Design System and the Technical Writer Word List.

How the writers apply the levels of edit

To balance quality, speed, and resource constraints, the technical writers apply different levels of edit to different documentation.

These guidelines are meant to provide general guidance. They aren’t set in stone, and they can be overridden on a case-by-case basis.

These items do not receive an edit unless it’s specifically requested (and if requested, they receive a light edit):

  • In the GitLab repository, the Contribution guidelines (in the /development directory).
  • In the GitLab repository, the doc/solutions directory. This information is owned by Solutions Architects.
  • In the GitLab repository, the blueprint documentation (everything in the architecture/blueprints directory).

These items receive a light edit:

  • Documentation outside of the five main GitLab repositories (GitLab, Charts, Operator, Omnibus, and Runner).
  • Deprecations and removals.
  • Merge requests authored by other technical writers, unless the MR is part of an OKR, or the author requests a more in-depth edit.

These items receive a medium edit:

  • Day-to-day product documentation requests:
  • Release post items

These items receive a heavy edit:

  • Topic type restructuring efforts (“CTRT”)
  • OKR work
  • UI text

In all cases, the Technical Writer confirms that an authoritative source has checked the documentation for technical accuracy. The Technical Writer can serve as that authoritative source if they have the required knowledge or can efficiently perform the necessary verification.

Review workflow

To balance velocity and quality, the writers use this workflow:

  • When a writer opens a merge request, another writer must review and merge. Peer reviews are important to maintain quality and help the team build a common voice.
  • When anyone else (like a developer, community member, or Support team member) opens a merge request:
    • If the MR contains documentation and code, the writer adds suggestions but does not merge. The MR is merged by another developer.
    • If the MR contains documentation only:
      • Writers can apply small suggestions, by using the Apply suggestion feature, before they merge. Writers can fix things like missing punctuation, typos, and pipeline failures without additional review.
      • Writers do not push larger changes (by using suggestions or commits) to the author’s branch unless they have explicit approval in the MR to do so. Pushing to a branch can cause hard-to-resolve merge conflicts, and content can be accidentally overwritten.
      • In rare cases, a writer has agreement from their team to make commits directly to the author’s branch. In these cases, if the writer pushes changes other than minor typo fixes (by using suggestions or commits), the author must review before the writer merges. This workflow gives the MR author a chance to verify the changes and it helps ensure accuracy.

For more information on review turnaround times, see Review-response SLO.

Triaging automated group mentions

When a bot or a community contributor mentions either @gl-docsteam or several Technical Writers based on CODEOWNERS, TWs should volunteer to:

  1. Scan the MR and either volunteer to review it or determine which TW should review it, following the guidelines in Selecting a reviewer.
  2. Then, if the MR:
    • Seems ready for review, assign the selected TW as a reviewer.
    • Doesn’t seem ready for review, leave a comment for the contributor asking them to mention the selected TW when they’re ready.
  3. Edit the bot’s comment and format the team mention as code. For example: Hi `@gl-docsteam`! Please review this documentation merge request. This removes other TWs from the MR’s participants list, and they will no longer receive notifications for it. The to-do notification will be updated to show the username in backticks, so team members working from their to-do list will have a visible hint that the MR has been addressed.

Selecting a reviewer

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.

Determining Technical Writer availability

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 preceding the release date, 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).

Merge rights

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:

  • Documentation, typically in Markdown-formatted files.
  • UI text, error messages, and link-related fixes, with the approvals of appropriate engineer(s).
  • Documentation-related tooling and configuration such as linters, and changes to the gitlab-docs project. Engineers are available for code review and merges.

In addition, Technical Writers should:

  • Never merge an MR with a failed pipeline, unless the failures are unrelated to the changes. If in doubt, ask an engineer.
  • Ensure that MRs are complete before merging, with appropriate labels and milestones.
  • Ensure that the DRI has reviewed and approved the MR.

Onboarding Technical Writers

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 more information about onboarding phases and tasks, see the Technical Writer onboarding template.

Standups

We have set up Geekbot for our twice weekly standups (at 10:00 AM, Tuesday and Thursday, 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:

  1. Visit the Geekbot dashboard and sign in using your Slack account when asked.
  2. Select the Tues/Thurs ping standup and search the member by name in the Add participants area.
  3. Give the newly-added member Manage access and select Save in the upper right corner.

To add a new member to the Weekly Wednesday Question standup:

  1. Visit the Geekbot dashboard and sign in using your Slack account when asked.
  2. Select the Weekly Wednesday Question standup and search the member by name in the Add participants area.
  3. Give the newly-added member manage access and select Save in the upper right corner.

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:

  1. Visit the Weekly Wednesday Questions.
  2. Under the Questions section, you can see a “This is a random set of questions” question. Hover over the two arrows on the right, and select Edit.
  3. Scroll to the bottom and select Add question.
  4. Select Save questions.

Community contribution opportunities

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:

Documentation process

See:

Make an urgent content update on docs.gitlab.com

The documentation website is refreshed every hour. On rare occasions, we might have to publish documentation updates a little faster. If you need an urgent update, follow the steps to manually deploy the docs site.

Report a docs website problem or infrastructure issue

Report website bugs or feature requests in the issue queue for the Docs website.

For outages or website availability issues, see Docs site infrastructure.


Hiring Technical Writers
As GitLab grows, the Technical Writing team expands, and team members participate in interviews. A defined interview process is important for a consistent hiring process. Hiring process General resources: Interviewing at GitLab Technical Writing Manager job family Technical Writing job family Interviews for Technical Writing The following people interview the candidate for a Technical Writing role: Technical Writer Technical Writing Manager Product Manager or Customer Support representative Technical Writing Senior Manager The goal is to evaluate the candidate’s technical skills and knowledge, such as:
Setting up a local environment
Whether you are a contributor or a GitLab Technical Writing team member, one of your first tasks is to set up an environment on your computer for writing and previewing GitLab documentation. Tools for technical writers You can use the following tools to set up your environment. Most of these are not compulsory - you can set up your environment however you choose. These are simply suggestions to help you get up and running quickly:
Technical Writing Fundamentals
The Technical Writing Fundamentals course is available to help both GitLab and community contributors write and edit documentation for the product. This course provides direction on grammar and topic design. This class is not required to contribute to docs.gitlab.com. Everybody can contribute! You can review the training materials on this page, or you can take the course in Level Up. Technical Writing Fundamentals course The Technical Writing Fundamentals course consists of the following sections to be completed in order.
Technical Writing workflows
Technical Writing team workflows work in conjunction with the: Product development flow. Product designer workflow. Engineering workflow. The process for creating and maintaining GitLab product documentation depends on whether the documentation is: A new feature or feature enhancement: Delivered for a specific milestone and associated with specific code changes. This documentation has the highest priority. Changes outside a specific milestone: Usually not associated with a specific code change, is of lower priority, and is open to all GitLab contributors.
Last modified March 19, 2024: Add latest doc site stats (0e2f6148)