The GitLab Technical Writing team plays a crucial role in developing effective product documentation. They work closely with developers, product managers, and the community to ensure that the documentation keeps up with the evolving needs of GitLab's customers, users, and administrators.
Good documentation is essential because it educates readers about the features and best practices of GitLab. It also helps people efficiently configure, use, and troubleshoot GitLab, making it easier for them to get the most out of the platform. The team responsible for managing the docs.gitlab.com site and its content, processes, and tooling is known as the Technical Writing team.
To continually improve the quality of the documentation, the team follows a roadmap that drives their efforts. One area of focus is ensuring that people can easily find the information they need on the docs.gitlab.com site. To achieve this, the team has set several roadmap items and OKRs (Objectives and Key Results). Some of these include replatforming the docs site, providing better task-based information, and making content more accessible and easy to find. By completing these larger projects alongside feature documentation, the team is able to provide continual, iterative improvement to the user experience of their documentation.
Anyone can contribute to the documentation by following our GitLab documentation guidelines. The team manages general documentation-related and team-specific Slack channels, including #docs, #docs-processes, #docs-tooling, gitlab-docs, #docs-site-changes, gitlab-docs, #tw-team, and #tw-social.
The Technical Writing team is responsible for updating or creating GitLab product documentation. They are assigned to specific DevOps stage groups, with a broad responsibility for developing documentation content and UI text while helping others develop content.
If you're interested in contributing to documentation for GitLab, consider taking the Technical Writing Fundamentals course. It includes guidelines for technical writing, GitLab style conventions, information about internal testing, instructions for content types, and more.
In addition to managing documentation channels, the Technical Writing team maintains documentation for many engineering projects and occasionally develops new content to meet the needs of the community. Contact us if you have any questions or want to get involved in this effort.
The role of Technical Writer in the product development process involves several key responsibilities, including reviewing and collaborating on documentation plans, ensuring content meets style and language standards, reorganizing and improving documentation to enhance user experience, and collaborating with Product Designers on UI text. Additionally, they act as the Technical Writing Lead for the monthly release post.
When it comes to prioritizing tasks, the team follows a specific order. They prioritize Feature work, OKR-related work, Backlog issues, and All other tasks. This ensures that the team is focusing on the most important aspects of the product development process and making the necessary improvements to meet stakeholder needs.
In terms of processes, the Technical Writing team is responsible for developing and maintaining efficient processes. This includes reviewing and collaborating on documentation plans, reviewing doc merge requests or recently merged docs, and ensuring that content meets style and language standards. The team also focuses on reorganizing, revamping, and authoring improved documentation to ensure completeness and a smooth user experience. Collaboration with Product Designers on UI text, such as microcopy, links from the UI to documentation, error messages, and UI element labels, is also a key aspect of their work. Finally, acting as the Technical Writing Lead for the monthly release post is an important responsibility for this role.
Ensuring that processes are in place and being followed to keep the GitLab docs up to date is a crucial task for our Documentation team. We have a set of standard processes, which we follow on a regular basis, to ensure that the documentation is always up-to-date and accurate. This process includes working closely with the Product and Engineering teams to optimize documentation workflows, as well as dividing tasks and responsibilities between the Documentation Team and others.
In addition to these ongoing processes, we also spend time triaging doc-related issues that may arise. This involves reviewing and prioritizing support tickets or other documentation-related issues, so that they can be addressed quickly and effectively. We also work to refine our Documentation Style Guide, which provides language and style guidance for our product documentation and release posts. Our goal is to continuously improve content about GitLab documentation and its contribution process, so that it is easier for anyone to contribute to the documentation while efficiently handling community contributions.
We use specific tools and techniques to ensure the quality of our documentation, such as testing scripts like lint-doc.sh. These scripts help us catch common problems early in the development process, so that they can be fixed before they become more serious issues.
Finally, we are committed to making our documentation available in multiple languages and formats, including translated versions of our documentation and internationalization efforts. By doing so, we hope to make it easy for users all over the world to understand and use GitLab's products and services.
Translation of GitLab from English into other languages can be contributed by everyone. To gain insight into translation and internationalization at GitLab, visit the Import and Integrate direction page and Manage stage Category Direction page on Internationalization. For a comprehensive guide on contributing to translation efforts, read Translating GitLab.
It is important to note that the docs.gitlab.com site falls outside the scope of community-driven internationalization efforts for GitLab. Discussion related to translating documentation into different languages can be found in this particular issue.
Technical Writers (TWs) should collaborate with their assigned groups. TWs may also have additional responsibilities beyond their primary duties. However, it is worth noting that some content on docs.gitlab.com is not reviewed by TWs.
The role of a Technical Writer is critical for the success of documentation projects. They act as the primary point of contact for their assigned groups, collaborating with other team members to ensure that documentation is accurate, up-to-date, and meets the needs of users. In this section, we will discuss the various roles and responsibilities of a Technical Writer in each stage of a documentation project.
## Stage 1: Planning
In this stage, the Technical Writer is responsible for planning new documentation by working with subject matter experts (SMEs) to understand the user needs and requirements. They identify the key information that needs to be included in the documentation and create an outline or structure for the content. This may involve research, data analysis, and collaboration with stakeholders to ensure that the documentation is comprehensive and effective.
## Stage 2: Writing and Editing
Once the planning stage is complete, the Technical Writer begins writing and editing the documentation. This involves creating clear and concise language that is easy for users to understand, while also providing detailed information about features, functionality, and usage. TheTechnical Writer must also review any proposed changes to documentation and provide feedback to ensure that it accurately reflects the product or service being described.
## Stage 3: Reviewing and Approval
After the documentation has been written and edited, it is reviewed by other team members and subject matter experts to ensure that it is accurate, comprehensive, and user-friendly. Any proposed changes are discussed and approved before finalizing the documentation. This ensures that the documentation is of high quality and meets the needs of users.
## Stage 4: Collaboration with Team Members
Throughout each stage of the documentation project, the Technical Writer collaborates closely with other team members to ensure that the documentation is effective and meets the needs of users. This includes working with designers, developers, testers, and other stakeholders to ensure that the documentation is aligned with the product or service being described.
## Stage 5: Conclusion
In conclusion, Technical Writers play a crucial role in ensuring that product or service documentation is accurate, up-to-date, and effective. By collaborating with other team members, they can help to deliver high-quality documentation that meets the needs of users. Whether working on a large software project or a simple how-to guide, Technical Writers are essential for creating effective documentation that helps users get the most out of a product or service.
Technical writers are encouraged to review and improve documentation of other stages, but they are not required to do so. When contributing to documentation that is not their own, they must respect the assigned technical writer's ownership and ensure to request their review and approval when making significant changes to the documentation. In situations where a technical writer is on leave (PTO), the entire team acts as their backup.
In addition, some technical writers are appointed stage leads for specific DevOps stages:
* Stage: Verify
* Assigned stage lead: AI-powered ModelOps
* Stage: Create
* Plan
* Stage: Secure
* Assignments to other projects and subjects
* Subject: Assign technical writer
* The documentation site:
* The documentation site backend (code, automation)
* Left nav (information architecture of documentation)
* Content not reviewed by technical writers:
* doc/architecturedoc/developmentdoc/development/doc/development/documentationdoc/solutionsgitlab-docs
Subject: Docs site Stats
The technical writing team supports a large amount of content. The following is an overview of the current status of our Docs site, including page count information and changes between quarters.
Page Count by Area of the Left Nav
In August 2024, the number of pages in the five primary repositories (GitLab, Omnibus, Charts, Operator, and Runner) was as follows:
- GitLab: 379 pages
- Omnibus: 108 pages
- Charts: 365 pages
- Operator: 120 pages
- Runner: 345 pages
A total of 1,307 pages were added or removed from these repositories compared to the previous quarter.
Date| # of Pages| Change from Previous Quarter
---|---|---
September 2024| 2,328| -5%
June 2024| 2,456| +6%
March 2024| 2,308| +5%
December 2023| 2,201| +5%
September 2023| 2,088| +8%
June 2023| 1,993| +5%
March 2023| 1,929| +3%
December 2022| 1,840| -
September 2022| 1,785| -
June 2022| 1,633| -
January 2022| 1,562| -
May 2020| 1,165| -
Change between May 2020 and September 2024:
+1,163 more pages (a 99% increase)
以下是重构后的内容：
从2020年5月到2024年9月，文章字数增加了200,982字(增长了168%) 。这是由于将架构蓝图主题移动到手册中导致的减少。有关更多信息，请参见第279期。在此期间，文章字数翻了一番以上。
2024年8月，左侧导航栏中的文章字数按区域划分。
分析
https://
要对仪表板进行更改或提出建议，请在“市场营销战略和分析”项目中打开问题。技术作家的PTO
When Technical Writers need to take paid time off from their work, it is important for the rest of the team to be able to cover for them. This may involve additional context or information being gathered to ensure that requests are properly integrated into the list of stage/group and feature priorities. To help facilitate this process, there are several options available to groups who need assistance while an assigned Technical Writer is on vacation.
For those who will be taking extended PTO (more than one week), it is recommended that Technical Writers consider using the Technical Writer coverage issue. This issue can provide detailed information about who is providing coverage, what needs to be covered, and how it will be done.
When a Technical Writer is taking PTO, they should make themselves available via email and other communication channels in order to respond to urgent named time-sensitive task matters. For more general inquiries, they can refer back to the documentation provided by the handbook: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#technical-writer-pto
Additionally, the merge request queue should be checked periodically during the absence of the Technical Writer to ensure that any outstanding tasks are being properly addressed. If there are any concerns or issues that need to be addressed while the Technical Writer is away, they can be communicated with the relevant team members through email or other means.
This document outlines the process for checking Technical Writer's Merge Request (MR) queue before a writer goes on PTO. The assigned person should review the queue at least once daily in the GitLab Review Workload Dashboard to ensure that all documentation changes are reviewed and approved before the writer leaves on PTO.
The assigned writer does not need to do the work of checking the queue. Instead, they can use Roulette to find other Technical Writers (TWs) who are available to review their MRs. Additionally, they can assign their own MRs for review or schedule tasks for Docs project maintenance as needed.
Regularly scheduled tasks include reviews of merge requests containing documentation changes authored by GitLab team members and community contributors. Reviews are assigned by subject matter according to the Technical Writer assignments to stage groups or other specialties. The Technical Writers use the following levels of edit:
- Light: Minor changes only
- Medium: Minor and major changes
- Heavy: Major and structural changes
By following this process, Technical Writers can ensure that all documentation changes are reviewed and approved before they leave on PTO, allowing them to effectively manage their time off while still maintaining high quality documentation for their projects.
Editing level| Criteria
---|---
Light| Ensure the pipeline passes and no obvious grammar, spelling, or punctuation errors exist.
Medium| 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 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.
In this table, we have defined three levels of editing: Light, Medium, and Heavy. The criteria for each level are listed in a separate row under the corresponding level column. The first two criteria focus on ensuring that the pipeline passes and that the content is clear and user-friendly. The third criterion adds additional requirements related to topic type, consistency, and style. Finally, the fourth and fifth criteria specify specific standards that must be met for UI text content.
To balance quality, speed, and resource constraints, technical writers apply different levels of edit to documentation based on specific guidelines. While these guidelines aim to provide general guidance, they are not rigidly fixed and can be overridden on a case-by-case basis.
The following items do not receive an edit unless specifically requested:
* /developmentdoc/solutionsarchitecture/blueprints
Items that receive a light edit are those outside of the five main GitLab repositories, including:
* Documentation outside of GitLab, Charts, Operator, Omnibus, and Runner.
* Deprecations and removals.
* Merge requests authored by other technical writers unless part of an OKR or the author requests a more in-depth edit.
When it comes to day-to-day product documentation requests, the following items receive a medium edit:
* Improvements
* Bug fixes
* Community contributions
* Release post items
Finally, items that receive a heavy edit include:
This document describes the technical writing and review process of a software development team. It covers topics such as CTRT, OKR work, UI text, review workflow, and how to apply small suggestions to documentation.
1. Topic Type Restructuring Efforts (CTRT)
The Technical Writers confirm that an authoritative source has checked the documentation for technical accuracy. If they have the required knowledge or can efficiently perform the necessary verification, they can serve as that authoritative source. This helps ensure consistency in technical writing across the team.
2. OKR Work
The team focuses on Objectives and Key Results (OKRs) to achieve its goals. These objectives are aligned with the company's strategic vision and are measurable within a set timeframe. The team works together to create and prioritize these objectives, ensuring that everyone is clear on their responsibilities and progress towards them.
3. UI Text
The Technical Writers play a crucial role in ensuring the accuracy and quality of the UI text throughout the software development lifecycle. They work closely with developers, community members, and Support team members to ensure that all UI text is consistent and meets the team's standards.
4. Review Workflow
To balance velocity and quality, the writers use a specific workflow when reviewing merge requests (MRs). When a writer opens an MR, another writer must review and merge it. Peer reviews are important to maintain quality and help the team build a common voice.
If anyone else (e.g., a developer, community member, or Support team member) opens an MR containing documentation or code, the writer adds suggestions but does not merge the MR themselves. The MR is merged by another developer instead.
However, if an MR contains only documentation, the writer can apply small suggestions using the Apply suggestion feature within GitHub. This allows the author of the MR to see suggested changes in context before deciding whether to accept them or not.
In this workflow, before a merge request can be merged into the author's branch, it must go through several checks and approvals.
First, the system automatically triages any automated group mentions in the title or description of the merge request to identify potential issues.
Next, writers are able to fix common mistakes such as missing punctuation, typos, and pipeline failures without needing additional review. However, they are not allowed to push larger changes (such as suggestions or commits) to the author's branch without explicit permission from the MR author.
Pushing to a branch can cause merge conflicts that may be difficult to resolve and content may be accidentally overwritten.
In rare cases, a writer may have agreed with their team to make commits directly to the author's branch. If this is the case, the MR author must review the changes before the writer merges. This ensures accuracy and gives the author time to verify the changes.
If there are any questions about review turnaround times, refer to the Review-response SLO.
In most cases, Technical Writers should use the GitLab Review Workload Dashboard to identify someone for a technical writing review. To do this, 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 some specific cases, where the selected Technical Writer already has a lot of assigned reviews or has recently been very busy, you can repeat the process by selecting "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 situations, you can specifically assign the review to that person. This ensures that the review is given to the right person and that it is completed in a timely manner.
Determining Technical Writer availability is important for ensuring that your team has the necessary resources to complete the work efficiently. 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. This allows other team members to understand that they may need to wait until after that week to schedule a review with them. By doing this, they can focus on release posts and other requirements while still ensuring that the technical writing is completed to a high standard.
In certain cases, Technical Writers can modify their profiles by adding or removing the busy indicator. However, it is important that the busy indicator is used for no longer than two days at a time and not more than once every two weeks. This rule applies regardless of whether the busy indicator is being used during a release. If you need additional time to participate in the review roulette, it is recommended to speak with your manager to determine if additional use of the busy indicator is possible.
Merge rights are granted to Technical Writing team members as part of their role in GitLab projects through maintainer access. It is important for these members to exercise this privilege responsibly by limiting what they merge. Specifically, Technical Writers must only merge changes to the following repository: gitlab-docs.gitlab/CODEOWNERS. Additionally, there are specific requirements for merging merge requests (MRs):
1. Never merge an MR with a failed pipeline.
2. Ensure that the MR is complete before merging, including the use of appropriate labels and milestones.
Onboarding Technical Writers
The DRI ensures that the MR is reviewed and approved before onboarding the Technical Writer. During the onboarding process, the Technical Writer will be shadowed by members of a group and begin contributing as trainees. Veteran Technical Writers will provide guidance and coaching throughout this phase. If you require more information about the onboarding process and tasks, refer to the Technical Writer onboarding template.
Standups
The team has established two weekly standups using Geekbot (on Tuesdays and Thursdays at 10:00 AM local time). Additionally, a random weekly question runs on Wednesdays at 12:00 PM. All members have access to edit and manage these standups. To add a new member to the daily standup, follow these steps:
1. Visit the Geekbot dashboard and sign in with your Slack account when prompted.
2. Select the "Tues/Thurs ping standup" from the list of available standups.
3. Search for the desired member by name in the "Add participants" field.
4. Give the newly-added member "Manage access" permissions and click "Save" in the upper right corner.
5. For adding new members to the Weekly Wednesday Question standup, follow similar steps as mentioned above.
As a member of your organization's Technical Writing team, you are responsible for managing access to the Geekbot dashboard in Slack. Here's how you can do it:
1. Visit the Geekbot dashboard and sign in using your Slack account when prompted.
2. In the top right corner, click on the "Add participants" button.
3. Search for the member by name in the "Add participants" area and select their name from the list.
4. After selecting the member, give them manage access by clicking on the "Manage Access" button next to their name.
5. Finally, click on the "Save" button in the upper right corner to save your changes.
If you would like to add your own question to the Weekly Wednesday Question standup, follow these steps:
1. Under the "Questions" section, you will see a "This is a random set of questions" question. Hover over the two arrows on the right side of the question and select "Edit."
2. Scroll down to the bottom of the page and select "Add question."
3. Choose a title for your question and enter it into the text box provided. You can also add any additional information or details about your question in the appropriate fields.
4. Click on the "Save questions" button at the bottom of the page to save your changes and add your new question to the list.
Remember that we welcome improvements to content as well as developments to our documentation website at https://docs.gitlab.com. If you have any ideas for how to make our documentation even better, please don't hesitate to share them with us! For more information about community contributions, please refer to the Documentation process documentation page or reach out to your manager or local GitLab support team for further assistance.
This documentation website is updated every hour, though in rare circumstances we might need to publish updates even faster. If you require an urgent update, refer to the following steps to manually deploy the docs site.
If you experience any issues with the documentation website or its infrastructure, please report them in the appropriate issue queue for the Docs website. For any outages or issues related to website availability, please consult the Docs site infrastructure.
