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:
- A group of Technical Writers.
- Two Technical Writing Managers.
- A Senior Fullstack Engineer, Technical Writing.
- A Technical Writing Director.
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 thegitlab-docs
project.#docs-site-changes
: Automated messages fromgitlab-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.
Assignments to other projects and subjects
For collaboration in other projects and subjects:
Subject | Assigned technical writer |
---|---|
The documentation site | Susan Tacker |
The documentation site backend (code, automation) | Sarah German |
GitLab Design System (“Pajamas”) information under content |
Suzanne Selhorn |
Style Guide | Suzanne Selhorn |
Testing/Vale/markdownlint | Diana Logan |
Documentation handbook | Diana Logan |
Technical Writing handbook | Susan Tacker |
Tutorials | Kati Paizee |
What’s new | Kati Paizee |
GitLab Development Kit (GDK) | Ashraf Khamis , Achilleas Pipinellis , Evan Read , Fiona Neill , Jon Glassman , Lorena Ciutacu , Marcel Amirault , Phillip Wells , Russell 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 thedoc/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:
-
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:
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 thetechnical-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:
- April, 2024: Lysanne Pinto
- March, 2024: Amy Qualls
- February, 2024: Marcel Amirault
- January, 2024: Phillip Wells
- December, 2023: Achilleas Pipinellis
- November, 2023: Marcin Sędłak-Jakubowski
- October, 2023: Russell Dickenson
- September, 2023: Evan Read
- August, 2023: Kati Paizee
- July, 2023: Diana Logan
- June, 2023: Ashraf Khamis
- May, 2023: Fiona Neill
- April, 2023: 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
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:
- New feature work (from stage groups or Incubation engineers)
- Improvements
- Bug fixes
- Community contributions
- 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:
- 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. 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:
- 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.
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:
- Technical writing workflow in the handbook.
- Documentation workflows in the contributor documentation.
- Setting up a local environment in the handbook.
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.
Setting up a local environment
Technical Writing Fundamentals
Technical Writing workflows
0e2f6148
)