Technical Writing

Technical writers shape the product experience, applying their expertise to the content that determines how users understand, interact with, and adopt GitLab features. We define how GitLab features are communicated across documentation and UI text, ensuring content is clear, accurate, and easy to use. We influence product direction by bringing a deep understanding of how words shape user success in a rapidly evolving DevSecOps platform.

Our team maintains content quality across all product areas for every release cycle. Guided by our documentation roadmap, we continuously improve our documentation and processes to meet the needs of both human readers and AI tools. We achieve this by:

• Refining content and findability based on UX research and user feedback.
• Providing strategic expertise for special projects and docs.gitlab.com features.
• Optimizing operations for the creation, management, and deployment of documentation using AI workflows, deterministic testing, and linting.

Documentation

The documentation is an essential part of the product. Its source is developed and stored with the product in its respective paths in the GitLab repositories. It’s published at docs.gitlab.com (offering multiple versions of all product documentation) and at the /help/ path on each GitLab instance’s domain, with content for that instance’s version.

The documentation is the single source of truth for all product information. We follow a docs-first methodology with the goal of creating documentation that is complete, accurate, and easy to use. Whether a user is browsing the site or an AI agent is searching for context, the information must be easy to find, consume, and contribute to.

To get started contributing to the documentation, see contribute to the GitLab documentation. For standards and guidelines, see the Documentation Style Guide and recommended word list.

Learn GitLab technical writing fundamentals

If you’re interested in updating or creating GitLab documentation, consider taking our GitLab Technical Writing Fundamentals course. This course is aimed at both GitLab team members and community contributors and includes:

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

This course is recommended but optional. You don’t need to complete it before you start. Everyone can contribute!

About us

The Technical Writing team manages the documentation site and its content, processes, and tooling. The roles in our team include:

• Technical Writers
• Technical Writing Managers

Contact us

You can contact us through Slack channels or the dedicated GitLab group aliases. For merge request reviews, check the docs page metadata and assign or mention the designated Technical Writer directly.

Slack channels

The team manages general documentation 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-engineering: Discussion about the documentation site and other engineering projects.
• #docs-processes: Discussion about documentation processes.
• #docs-tooling: Discussion about documentation tooling.
• #docs-site-changes-hugo: Automated messages from the docs-gitlab-com project.
• #tw-team: Technical Writing team chat.
• #tw-social: Technical Writing team social chat.

GitLab group aliases

Some team members are part of specific groups. To contact all the members of those groups in a GitLab issue or merge request, use the following aliases:

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.
• Reviewing and publishing the monthly release notes.

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. Quarterly objectives
3. Docs improvements and backlog issues (including stage lead work, docs technical debt, and topic type implementation)
4. All other tasks (including DocOps tasks)

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.
• Maintaining and improving documentation workflows and Technical Writing team processes.
• Triaging docs 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.

Documentation Style Guide

The Documentation Style Guide provides language and style guidance for the product documentation and release notes.

Anyone can suggest documentation style updates by creating an issue or merge request with the ~tw-style label and then assigning the issue or merge request to the designated Technical Writer. GitLab team members can also use the #docs Slack channel.

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, see internationalization. For a step-by-step guide to translation contributions, see translating GitLab.

The docs.gitlab.com site is available in English and Japanese. To learn more about the localization process, see product documentation localization.

Assignments

Technical Writers collaborate with their assigned groups. Technical Writers can also be assigned other strategic projects.

Some content on docs.gitlab.com is not reviewed by Technical Writers.

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 partner with subject-matter experts in all situations where documentation is required.

Section	Stage	Group	Assigned Technical Writer
AI	Agent Foundations	Agent Developer	Fiona Neill
AI	Agent Foundations	Agent Execution	Fiona Neill
AI	Agent Foundations	AI Catalog	Fiona Neill
AI	AI Clients	Developer Clients	#docs
AI	AI Clients	Duo Chat	#docs
AI	AI Clients	Duo Client SDK	#docs
AI	AI Coding	Code Review	Uma Chandran
AI	AI Coding	DAP Events	Uma Chandran
AI	AI Coding	DAP Repository Flows	Uma Chandran
AI	AI Platform	AI Core Infra	Ashraf Khamis
AI	AI Platform	AI Model Services	Ashraf Khamis
Analytics	Analytics	Analytics Instrumentation	#docs
Analytics	Analytics	Global Search	#docs
Analytics	Analytics	Optimize	Lorena Ciutacu
Analytics	Analytics	Platform Insights	#docs
Analytics	Orbit	Context Systems	#docs
CD	Deploy	Environments	#docs
CI	Package	Container Registry	Zach Painter
CI	Package	Package Registry	Zach Painter
CI	Verify	CI Platform	Roshni Sarangadharan
CI	Verify	Mobile DevOps	#docs
CI	Verify	Pipeline Authoring	Marcel Amirault
CI	Verify	Pipeline Execution	Lysanne Pinto
Data Science	ModelOps	DataOps	#docs
Data Science	ModelOps	MLOps	#docs
Database Excellence	Database Excellence	Database Architecture	#docs
Database Excellence	Database Excellence	Database Automation	#docs
Database Excellence	Database Excellence	Database Health	#docs
Dev	Create	Remote Development	#docs
Dev	Create	Repository Services	Brendan Lynch
Dev	Create	Source Code Triage	Brendan Lynch
Dev	Create	Source Code Hardening and Modernization	Brendan Lynch
Dev	Create	Source Code Investigation	Brendan Lynch
Dev	Plan	Planner Intelligence	Brendan Lynch
Dev	Plan	Planning Views	Brendan Lynch
Dev	Plan	Portfolio Planning	Brendan Lynch
Dev	Plan	Spec-Driven Development	Brendan Lynch
Dev	Plan	Work Items	Brendan Lynch
Developer Experience	Developer Experience	API	Isaac Durham
Developer Experience	Developer Experience	Development Health	#docs
Developer Experience	Developer Experience	Development Tooling	#docs
Developer Experience	Developer Experience	Performance Enablement	#docs
Developer Experience	Developer Experience	Test Governance	#docs
Foundations	Foundations	Accessibility	#docs
Foundations	Foundations	Design System	#docs
Fulfillment	Fulfillment	Cost Management	Lorena Ciutacu
Fulfillment	Fulfillment	Entitlements	Lorena Ciutacu
Fulfillment	Fulfillment	Seat Management	Lorena Ciutacu
Fulfillment	Fulfillment	Usage Visibility	Lorena Ciutacu
GitLab Delivery	GitLab Delivery	GitLab Build	Evan Read
GitLab Delivery	GitLab Delivery	Operate	Evan Read
GitLab Delivery	GitLab Delivery	Release and Deploy	#docs
Growth	Growth	Acquisition	#docs
Growth	Growth	Activation	#docs
Growth	Growth	Engagement	#docs
Monetization	Monetization	Billing Engine	#docs
Monetization	Monetization	Compliance	#docs
Monetization	Monetization	Observability, Monitoring, and Integrations	#docs
Monetization	Monetization	Platform and Infrastructure	#docs
Monetization	Monetization	Purchase	Lorena Ciutacu
Monetization	Monetization	Subscription Lifecycle	Lorena Ciutacu
Primitives	Async	Async	#docs
Primitives	Events Platform	Events Platform	#docs
Primitives	Hosted Runners	Dedicated Hosted Runners	#docs
Primitives	Hosted Runners	Hosted Runners Platform	#docs
Primitives	Runner & Functions Runtime	CI Functions Platform	Roshni Sarangadharan
Primitives	Runner & Functions Runtime	Runner Core	Roshni Sarangadharan
Primitives	Trigger	Trigger	#docs
Primitives	Workflow Engine	Workflow Engine	#docs
GitLab SaaS Production Engineering	GitLab Dedicated	Dedicated Migrations	#docs
GitLab SaaS Production Engineering	GitLab Dedicated	Environment Automation	Lysanne Pinto
GitLab SaaS Production Engineering	GitLab Dedicated	Geo	#docs
GitLab SaaS Production Engineering	GitLab Dedicated	Import	Evan Read
GitLab SaaS Production Engineering	GitLab Dedicated	US PubSec	Lysanne Pinto
GitLab SaaS Production Engineering	GitLab Dedicated	Switchboard	Lysanne Pinto
GitLab SaaS Production Engineering	Production Engineering	Cloud Cost Utilization	#docs
GitLab SaaS Production Engineering	Production Engineering	Fleet Management	#docs
GitLab SaaS Production Engineering	Production Engineering	Networking and Incident Management	#docs
GitLab SaaS Production Engineering	Production Engineering	Observability	#docs
GitLab SaaS Production Engineering	Production Engineering	Runway	#docs
Sec	Application Security Testing	Dynamic Analysis	Roshni Sarangadharan
Sec	Security Factory	Agentic Security Flows	#docs
Sec	Security Factory	AI Security Research	#docs
Sec	Security Factory	Code Scanning	#docs
Sec	Security Factory	Code Security	#docs
Sec	Security Factory	Composition Analysis	#docs
Sec	Security Factory	Secret Detection	Roshni Sarangadharan
Sec	Security Factory	Security Foundations	#docs
Sec	Security Factory	Threat Research	#docs
Sec	Security Factory	Vulnerability Management	#docs
Sec	Security Governance	AI Control Plane	#docs
Sec	Security Governance	AI Governance	#docs
Sec	Security Governance	Compliance	#docs
Sec	Security Governance	Policy Engine	#docs
Sec	Security Governance	Policy Management	#docs
Sec	Security Governance	Security Controls	#docs
Sec	Security Platform	Abuse Engineering	#docs
Sec	Security Platform	Authentication	Isaac Durham
Sec	Security Platform	Authorization	Isaac Durham
Sec	Security Platform	Build Security	#docs
Sec	Security Platform	Dependency Firewall	#docs
Sec	Security Platform	GATE Core	#docs
Sec	Security Platform	GATE Infra	#docs
Sec	Security Platform	Secrets Manager (Application)	#docs
Sec	Security Platform	Secrets Manager (OpenBao)	#docs
Tenant Scale	Tenant Scale	Cells Infrastructure	#docs
Tenant Scale	Tenant Scale	Git	Evan Read
Tenant Scale	Tenant Scale	Gitaly	Evan Read
Tenant Scale	Tenant Scale	Organizations	Zach Painter
Tenant Scale	Tenant Scale	Transport	#docs

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 Technical Writer’s ownership and request their review and approval when making significant changes to their docs.

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

Section leads

Technical Writing Managers are assigned to key sections. The designated Manager is the go-to person for their assigned sections. They represent technical writing in the leadership group and act as the point of contact for the team.

Section	Assigned Manager
AI	Sarah Watt
Analytics	Robert Landry
CD	Sarah Watt
CI	Sarah Watt
Dev	Sarah Watt
Fulfillment	Robert Landry
GitLab Delivery	Robert Landry
Growth	Robert Landry
GitLab SaaS Production Engineering	Robert Landry Lysanne Pinto
Sec	Robert Landry
Tenant Scale	Robert Landry

These sections represent the following areas:

Area	Assigned Manager
AI, Core DevOps	Sarah Watt
Analytics & Monetization, Platforms, Security	Robert Landry

Stage leads

Some Technical Writers are assigned as stage leads for a given DevOps stage.

Stage	Assigned stage lead
Verify	Lysanne Pinto
Create	Brendan Lynch
Plan	TBD (on hold)
Application Security Testing	TBD (on hold)

Stage leads might work across an entire stage, or a subset of groups in the stage. They support other Technical Writers assigned to groups in the stage.

Stage leads:

• Assume the same responsibilities as Technical Writers, but with a more targeted focus on proactively creating and improving documentation for their assigned stage.
• Spend approximately 70% of their time reviewing issues and merge requests that developers author for new features and enhancements for their assigned groups.
• Spend the remainder of their time:
  • Creating and refining content to address documentation needs and gaps for their assigned stage (for example, writing tutorials and use-case-based content, restructuring existing content, and working on the information architecture).
  • Supporting other writers in the stage to contribute to documentation improvements.
• Complete a quarterly planning issue to outline the content gaps and improvements they aim to address over three milestones. The planning issue is automatically created and assigned to all Technical Writers in the stage on the 20th of the last month before the start of the quarter.
• Apply the relevant tw-lead label to documentation merge requests they drive or provide input on. This label allows us to track the improvements that come out of the stage lead process. GitLab team members can view the Tableau chart.
• Collaborate with other stage leads on documentation improvements.

As stage leads are assigned fewer groups, the goal is for them to spend 70% of their time on proactive work instead of 30%.

For documentation improvements, stage leads are responsible for creating an issue board to track ongoing and planned documentation enhancements and additions.

DocOps group

DocOps is like DevOps, but for documentation. It’s an approach to help streamline the creation, management, and deployment of documentation.

Some Technical Writers are members of the DocOps group, which is responsible for:

• Maintaining content quality through testing and linting in CI/CD pipelines and locally.
• Assisting Fullstack Engineers, Technical Writing with operations tasks when asked or when those engineers are not online (for example, helping with Pages configuration, deployments, scheduled pipelines, and review apps).
• Updating dependencies for linting tools, and rolling those updates out in upstream documentation projects.
• Monitoring the TW: DocOps issue board.

The DocOps group isn’t responsible for the documentation site’s code, infrastructure, or build scripts. DocOps tasks are prioritized below feature work and quarterly objectives.

Participation in the DocOps group is based on team requirements. To express interest in joining, speak to your manager.

Documentation testing

The DocOps group develops and maintains tools that test GitLab documentation and other technical content for problems. These tools include:

• Content and formatting: markdownlint, Vale, yamllint
• Link validity: Lychee
• File permissions and naming: lint-doc.sh

To suggest changes to our linting rules or tooling:

1. Create an issue or merge request with the ~tw-testing label.
2. Mention @gitlab-org/technical-writing/tw-docops on the issue or merge request.

Assignments to other projects and subjects

For collaboration in other projects and subjects:

Subject	Assigned team member
The documentation site	Sarah Watt , Robert Landry
The documentation site backend (code, automation)	Hiru Fernando
The documentation’s information architecture (content restructuring and major changes to left navigation)	Fiona Neill
GitLab Design System (“Pajamas”) information under content	Fiona Neill
Documentation Style Guide	Fiona Neill
Documentation testing (DocOps/Vale/markdownlint)	Sarah Watt
GitLab Development Kit (GDK)	Ashraf Khamis , Evan Read , Lorena Ciutacu , Marcel Amirault

Content not reviewed by Technical Writers

Technical Writers don’t review content in:

• 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. Solutions Architects create, review, merge, and maintain this information.

Stable counterparts

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

Docs site metrics and analytics

The Technical Writing team tracks documentation performance across three key areas: satisfaction, findability, and usefulness. We use a combination of data sources, including user surveys and feedback, Google Analytics, content audits, and site availability monitoring.

We track statistics in the six primary projects: GitLab, Omnibus, Charts, Operator, Runner, and CLI:

• There are more than 3,100 documentation pages and 4,400,000 words in the documentation projects.
• Since May 2020, the page count has increased by more than 165%, and the word count by more than 270%.
• The largest share of pages (30%) and words (30%) are in the Use GitLab section of the left navigation.

GitLab team members can view additional metrics on the documentation metrics dashboard and the Data Studio dashboard. For dashboard instructions, see Google Analytics.

Technical Writer PTO

When Technical Writers take paid time off, the rest of the team provides coverage for them. These team members might need additional context for requests. Covering writers fit these requests in alongside the priorities of their own groups.

When an assigned Technical Writer is on PTO, groups can:

• Use the Reviewer Roulette to select a Technical Writer, then mention or assign them on the issue or merge request.
• Post a request in the #docs channel in Slack, where an available Technical Writer can volunteer to pick it up.
• For specific, time-sensitive, in-progress work, mention a pre-arranged Technical Writer on the issue or merge request.

For extended PTO (one week or more), Technical Writers and Managers should use 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. Keep GitLab.com statuses up to date so that:

   • The Reviewer Roulette can make accurate suggestions.
   • The Technical Writing team can easily see the PTO status of all team members when checking the Reviewer Roulette.

2. Send a message in the group Slack channels indicating where to find the available mechanisms. For example:

   I'm off for the holidays (202y-mm-dd - 202y-mm-dd). For help with documentation while I'm away, see
   https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#technical-writer-pto.
   For urgent _named time-sensitive task_ matters, ping _named Technical Writer_.
   

Merge request queue checks

Before a Technical Writer goes on PTO, the writer or their manager should determine who will check the writer’s merge request queue. The assigned person should check the queue at least once a day, using one of the following:

• The Reviewer Roulette.
• The Merge requests page for the gitlab project, filtered by Reviewer.
• The merge request queue section in the coverage issue.

The person checking the queue doesn’t have to do the reviews themselves. When they check the queue, they can:

• Assign the merge requests to themselves for review.
• Use the Reviewer Roulette to find other Technical Writers to review.

Regularly scheduled tasks

Along with their assigned work, Technical Writers complete these recurring tasks each month:

• Release notes and documentation release: The assigned Technical Writer reviews the content of the release notes. At the end of the milestone, the writer publishes the release notes and creates the monthly release for the docs site.

• Docs project maintenance tasks: The assigned Technical Writer completes maintenance tasks for the documentation site and its content. To track this work, the writer creates an issue from the tw-monthly-tasks template in the team-tasks project. If work beyond what’s described in the maintenance issue is required, the Technical Writer creates merge requests and additional issues as needed.

Schedule

Version	Month	Release notes and documentation release	Maintenance tasks
19.9	February 2027	TBD	Evan Read
19.8	January 2027	Evan Read	Marcel Amirault
19.7	December 2026	Marcel Amirault	Isaac Durham
19.6	November 2026	Ashraf Khamis	Lorena Ciutacu
19.5	October 2026	Isaac Durham	Zach Painter
19.4	September 2026	Lorena Ciutacu	Roshni Sarangadharan
19.3	August 2026	Zach Painter	Fiona Neill

Previous schedule

Version	Month	Release post check	Monthly doc release	Maintenance tasks
19.2	July 2026	Roshni Sarangadharan	Fiona Neill	Achilleas Pipinellis
19.1	June 2026	Isaac Durham	Achilleas Pipinellis	Jon Glassman
19.0	May 2026	Achilleas Pipinellis	Brendan Lynch	Uma Chandran
18.11	April 2026	Jon Glassman	Uma Chandran	Ryan Lehmann
18.10	March 2026	Uma Chandran	Russell Dickenson	Brendan Lynch
18.9	February 2026	Ryan Lehmann	Kati Paizee	Evan Read
18.8	January 2026	Brendan Lynch	Evan Read	Marcel Amirault
18.7	December 2025	Evan Read	Marcel Amirault	Ashraf Khamis
18.6	November 2025	Marcel Amirault	Ashraf Khamis	Zach Painter
18.5	October 2025	Ashraf Khamis	Zach Painter	Lysanne Pinto
18.4	September 2025	Zach Painter	Lysanne Pinto	Isaac Durham
18.3	August 2025	Russell Dickenson	Isaac Durham	Lorena Ciutacu

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

Technical Writers use the following levels of edit.

Light edit

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

Medium edit

• 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 edit

Everything in a medium edit, plus:

• Ensure the content conforms to the defined topic types.
• Ensure the content fits well into the larger documentation set.
• For UI text, ensure the content meets the standards defined in the GitLab Design System (Pajamas) and the recommended word list.

How the writers apply the levels of edit

To balance quality, speed, and resource constraints, Technical Writers apply different levels of edit to different documentation.

These are general guidelines. Writers can adjust them case by case.

Content not reviewed by Technical Writers doesn’t receive an edit unless it’s specifically requested. If requested, it receives a light edit.

These items receive a light edit:

• Documentation outside of the six primary projects (GitLab, Omnibus, Charts, Operator, Runner, and CLI).
• Deprecations and removals.
• Merge requests authored by other Technical Writers, unless the merge request is part of a quarterly objective or the author requests a more in-depth edit.

These items receive a medium edit:

• Day-to-day product documentation requests:
  • New feature work (from stage groups)
  • Improvements
  • Bug fixes
  • Community contributions
• Release notes

These items receive a heavy edit:

• Topic type restructuring efforts
• Quarterly objectives
• 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, Technical Writers use this workflow:

• When a Technical Writer opens a merge request, another Technical Writer must review and merge.
  • The Technical Writer should not approve or merge their own merge request. Instead, they should request a review from a peer with Maintainer access. The reviewer merges it after the final approval.
    • This requirement aligns with the GitLab Code Review Guidelines and satisfies the GitLab Change Management Policy.
• When anyone else (like a developer, community member, or Support team member) opens a merge request:
  • If the merge request contains only documentation changes, the Technical Writer:
    • Reviews the content and offers suggestions.
    • Doesn’t make large changes (by applying suggestions or pushing commits) to the author’s branch unless the author explicitly agrees in the merge request. Pushing to a branch can cause hard-to-resolve merge conflicts, and content can be accidentally overwritten. If the writer does make changes, the author must review them before the writer merges, to help ensure accuracy.
    • Can apply small suggestions using the Apply suggestion feature if a merge request is nearly ready to merge. Writers can fix things like missing punctuation, typos, and pipeline failures without additional review.
    • Approves and merges the documentation merge request when it is ready.
  • If the merge request is primarily a code change that also contains a documentation update, the Technical Writer:
    • Offers suggestions for any documentation, UI text, and error message changes, but shouldn’t apply any suggestion themselves. Making any changes to a code merge request can cause pipelines to fail, as code and specs often need to be updated by the engineer to match technical writing suggestions.
    • Approves the merge request if the documentation changes are ready to merge.
    • Doesn’t merge code changes. An engineer who also reviews the code changes must merge the merge request.
  • If the merge request is primarily a documentation change, but also has a small code change to update a link to match the change, the Technical Writer:
    • Reviews the content using the same workflow as a documentation-only merge request.
    • Can merge only if the merge request has all required approvals.

For more information about 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, a Technical Writer should:

1. Scan the merge request and either volunteer to review it or determine which Technical Writer should review it, following the guidelines in Selecting a reviewer.
2. If the merge request:
   • Seems ready for review, assign the selected Technical Writer as a reviewer.
   • Doesn’t seem ready for review, leave a comment for the contributor asking them to mention the selected Technical Writer 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 Technical Writers from the merge request’s participants list, so they no longer receive notifications for it. The to-do notification updates to show the username in backticks, so team members working from their to-do list have a visible hint that the merge request has been addressed.

Selecting a reviewer

In most cases, Technical Writers should use the Reviewer Roulette to identify someone for a technical writing review. They should set the page’s filter to show only Technical Writers and sort by Assign events last 7 days.

To get an available Technical Writer, select Spin the wheel!. If the selected Technical Writer already has many assigned reviews or has been busy recently, you can select Spin the wheel! again to get a different writer.

If content needs a specific assignee, or if a merge request is for a page that has a DRI (such as the Documentation Style Guide), they can assign the review to that person.

Determining Technical Writer availability

Sometimes Technical Writers are 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:) emoji, 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 notes 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 used no more than once every two weeks. (Using the busy indicator during releases doesn’t count toward this limit.) If you need more time not participating in the Reviewer Roulette, be sure to talk to your manager so they can help (which might 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, so Technical Writers must use this privilege responsibly.

As Maintainers, Technical Writers must limit what they merge to:

• Documentation, typically in Markdown-formatted files.
• UI text, error messages, and link updates in code files, with the approvals of appropriate engineers. You can skip engineer approval and ask a member of the Technical Writing leadership team or the Technical Writing DocOps team to approve code changes when:
  • The only code changes in a documentation merge request are link fixes to match changes to documentation files or anchor names, and
  • The pipeline completed successfully.
• Documentation tooling and configuration, such as linters.
• Changes to the docs-gitlab-com project. Engineers are available for code review and merges.

In addition, Technical Writers must:

• Never merge a merge request with a failed pipeline.
• Ensure that merge requests are complete before merging, with appropriate labels and milestones.
• Ensure that the DRI has reviewed and approved the merge request.

Onboarding Technical Writers

While a new Technical Writer is onboarding, they’re assigned to shadow groups and then start contributing as trainees. Experienced Technical Writers 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 time zone) 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:

1. Go to the Geekbot dashboard and sign in with your Slack account when prompted.
2. Select the Tues/Thurs ping standup and search for 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.
4. Repeat these steps for the Weekly Wednesday Questions 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:

1. Go to the Weekly Wednesday Questions standup.
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. Enter your question.
5. Select Save questions.

Community contribution opportunities

We welcome contributions to the documentation content and to the documentation site.

For more information about community contributions, see:

• List of available issues
• docs-gitlab-com project

Make an urgent content update on docs.gitlab.com

The documentation site 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 list for the docs-gitlab-com project.

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

Related topics

• Documentation workflows
• Set up your local environment
• Documentation site architecture

View page source - Edit this page - please contribute.