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:
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:
- Feature work (including documenting new features, and providing guidance on UI text)
- OKR-related work
- Backlog issues (including docs technical debt and implementing content topic design)
- 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.
Note
If you were directed here from a documentation page’s metadata:
- The metadata doesn’t indicate developer ownership, but is meant to direct you to an appropriate technical writer.
- If you are part of a development group and would like to add metadata to documentation pages, create an issue in the Technical Writing repository for discussion. Additional discussion is in this issue.
- If the stage is listed as
none, see if there is a DRI or use roulette.
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.
Stage leads
Some Technical Writers are assigned as stage leads for a given DevOps stage:
Assignments to other projects and subjects
For collaboration in other projects and subjects:
Content not reviewed by TWs
Technical writers do not 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. 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.
Docs site stats
The technical writing team supports a large amount of content.
Page count
The number of pages in the five primary repositories (GitLab, Omnibus, Charts, Operator, and Runner):
| Date |
# of pages |
Increase/decrease from previous quarter |
| Sept 2024 |
2,328 |
-5 % |
| June 2024 |
2,456 |
6 % |
| 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 September 2024: 1,163 more pages (a 99% increase).
Decrease in September 2024 due to moving the architecture blueprints topics to the handbook. For more information, see issue 279.
Page count by area of the left nav
In August, 2024, the page count by area of the left navigation:
Word count
The number of words in these repositories:
| Date |
Word count |
Increase/decrease from previous quarter |
| Sept 2024 |
3,191,353 |
-4 % |
| June 2024 |
3,325,823 |
4 % |
| 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 September 2024: 2,000,982 more words (a 168% increase)
Decrease in September 2024 due to moving the architecture blueprints topics to the handbook. For more information, see issue 279.
The word count has more than doubled in this timeframe.
Word count by area of the left nav
In August, 2024, the word count by area of the left navigation:
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:
-
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.
-
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/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:
- March, 2025:
Brendan Lynch
- February, 2025:
Emily Sahlani
- January, 2025:
Marcin Sędłak-Jakubowski
- December, 2024:
Roshni Sarangadharan
- November, 2024:
Ryan Lehmann
- October, 2024:
Russell Dickenson
- September, 2024:
Marcel Amirault
- August, 2024:
Jon Glassman
- July, 2024:
Ashraf Khamis
- June, 2024:
Evan Read
- May, 2024:
Lorena Ciutacu
- April, 2024:
Lysanne Pinto
- March, 2024:
Amy Qualls
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 technical writers use this workflow:
- When a technical writer opens a merge request, another writer must review and merge.
Peer reviews are important to maintain quality and a common voice.
- When anyone else (like a developer, community member, or Support team member) opens a merge request:
- If the MR contains only documentation changes, the writer:
- Reviews the content and offers suggestions.
- Does not directly make large changes (by applying suggestions or pushing 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.
- Can use suggestions or commits to make changes themselves only if the writer has agreement from the author to make changes directly to the author’s branch.
In these cases, the author must always review the technical writer’s changes before the writer merges, to help ensure accuracy.
- Can apply small suggestions using the Apply suggestion feature if an MR is nearly ready to merge.
Writers can fix things like missing punctuation, typos, and pipeline failures without additional review.
- Approves and merges the documentation MR when it is ready.
- If the MR is primarily a code change that also contains a documentation update, the writer:
- Offers suggestions for any documentation, UI text, and error message changes, but should not apply any suggestion themselves.
Making any changes to a code MR can cause pipelines to fail as code and specs often need to be updated by the engineer to match technical writing suggestions.
- Approves the MR if the documentation changes are ready to merge.
- Does not merge code MRs. The MR must be merged by an engineer who also reviews the code change.
- If the MR is primarily a documentation change, but also has a small code change to update a link to match the change, the writer:
- Reviews the content using the same workflow as a documentation-only MR.
- Can merge only if the MR has all required approvals.
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:
- Scan the MR and either volunteer to review it or determine which TW should review it, following the guidelines in Selecting a reviewer.
- 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.
- 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, 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-related updates in code files, with the approvals of appropriate engineers.
You can skip engineer approval and ask a member of the TW leadership team
or
@marcel.amirault to approve code changes when:
- The only code changes in a documentation MR are link fixes to match changes to documentation files or anchor names, and
- The pipeline completed successfully.
- 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 must:
- Never merge an MR with a failed pipeline.
- 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:
- Visit the Geekbot dashboard and
sign in using your Slack account when asked.
- Select the Tues/Thurs ping
standup and search the member by name in the Add participants area.
- 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:
- Visit the Geekbot dashboard and
sign in using your Slack account when asked.
- Select the Weekly Wednesday Question
standup and search the member by name in the Add participants area.
- 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:
- Visit the Weekly Wednesday Questions.
- 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.
- Scroll to the bottom and select Add question.
- Select Save questions.
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.
GitLab documentation is crafted to help users, admins, and decision-makers
learn about GitLab features and to optimally implement and use GitLab to meet
their DevOps needs.
The documentation is an essential part of the product. Its source is developed
and stored with the product in its respective paths within 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.
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:
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:
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.
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:
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 team workflows work in conjunction with the:
The process for creating and maintaining GitLab product documentation depends on whether the documentation is:
Last modified December 12, 2024:
Update file _index.md (e6e9beb7)
#docs Slack channel
Phillip Wells
Suzanne Selhorn
Fiona Neill
Achilleas Pipinellis
Susan Tacker
Sarah German
Kati Paizee 