Technical Writing team workflows work in conjunction with the:
The process for creating and maintaining GitLab product documentation depends on whether the documentation is:
A new feature or feature enhancement: Delivered for a specific milestone and associated with specific code changes. This documentation has the highest priority.
Changes outside a specific milestone: Usually not associated with a specific code change, is of lower priority, and is open to all GitLab contributors.
Documentation is required for a milestone when:
Note: Documentation refactoring unrelated to a feature change is covered by the process for changes not related to a specific milestone, which allows for time-sensitive documentation updates to be prioritized.
Documentation isn't typically required when a backend feature is added or changed.
Documentation is required for any new or changed feature, and is:
Developers are the primary authors of documentation for a feature or feature enhancement. They are responsible for:
The first merge request where a feature can be tested should include the documentation, even if the feature is behind a feature flag. For details, see [the guidelines][https://docs.gitlab.com/ee/development/documentation/feature_flags.html).
The author of this MR, either a frontend or backend developer, should write the documentation.
Note: Community Contributors can ask for additional help from GitLab team members.
Because the documentation is an essential part of the product, if a
issue also contains the
~documentation label, you must ship the new or
updated documentation with the code of the feature.
Technical Writers are happy to help, as requested and planned on an issue-by-issue basis.
For feature issues requiring documentation, follow the process below unless otherwise agreed with the Product Manager and Technical Writer for a given issue:
Use the documentation requirements developed by the Product Manager in the issue and discuss any further documentation plans or ideas as needed.
If the new or changed documentation requires extensive collaboration or conversation, a separate, linked issue can be used for the planning process.
#docson GitLab Slack, if you:
Before merging, documentation changes committed by the developer must be reviewed by:
Product Managers are responsible for the documentation requirements for a feature or feature enhancement. They can also:
For issues requiring any new or updated documentation, the Product Manager must:
Everyone is encouraged to draft the documentation requirements in the issue. However, a Product Manager will:
Technical Writers are responsible for:
The Technical Writer:
~"type::feature"issues that are part of the next milestone to get a sense of the scope of content likely to be authored.
~documentationlabel on issues from that list which don't have it but should, or inquires with the PM to determine if documentation is truly required.
~directionissues from that list, reads the full issue and reviews its Documentation requirements section. Addresses any recommendations or questions with the PMs and others collaborating on the issue in order to refine or expand the Documentation requirements.
By default, the developer will work on documentation changes independently, but the developer, Product Manager, or Technical Writer can propose a broader collaboration for any given issue.
Additionally, Technical Writers are available for questions at any time.
Feature documentation requirements should be included as part of the issue for planning that feature in the Documentation section within the issue description. Issues created using the Feature Proposal template have this section by default.
Anyone can add these details, but the Product Manager who assigns the issue to a specific release milestone will ensure these details are present and finalized by the time of that milestone's kickoff.
Developers, Technical Writers, and others may help further refine this plan at any time on request.
The following details should be included:
Currently, the Technical Writing team strongly encourages including documentation in the same merge request as the code that it relates to, but this isn't strictly mandatory. It's still common for documentation to be added in an MR separate from the feature MR.
Engineering teams may elect to adopt a workflow where it is mandatory that documentation is included in the code MR, as part of their definition of done. When a team adopts this workflow, that team's engineers must include their documentation in the same MR as their feature code, at all times.
A workflow that has documentation separated into its own MR has many downsides.
If the documentation merges before the feature:
If the documentation merges after the feature:
Having two separate MRs means:
Documentation quality might be lower, because:
Including documentation with code (and doing it early in the development process) has many benefits:
To have documentation included with code as a mandatory workflow, some changes might need to happen to a team's current workflow:
Maintainers are allowed to merge features with the documentation as-is, even if the Technical Writer hasn't given final approval yet but the merge request has all other required approvals.
You can visualize the parallel workflow for code and documentation reviews as:
For complex features split over multiple merge requests:
A Product Designer should consult with the Technical Writer for their stage group when planning to add or change substantial text within the UI, such as a phrase of explanatory microcopy or a link to documentation.
The Technical Writer can offer an initial review of any ideas, plans, or actual text, and can be asked to draft text when provided with information on the context and goals of the text. Context may include detail on the scenarios in which the text would appear (for example, to all users viewing the feature or only under certain conditions), and the information to convey, which typically answers one or more of the questions:
Once the merge request is created, all changes and additions to text in the UI must be reviewed by the Technical Writer in accordance with review principles.
These may include: labels (buttons, menus, column headers, UI sections) or any phrases that may be displayed within the UI, such as user-assistance microcopy or error messages.
Additional information about composing and reviewing UI text:
When a new GitLab version is released, the Technical Writing team releases version-specific published documentation.
To make a documentation change that is not associated with a specific code change, the Technical Writing team encourages contributors to start with an MR and follow the documentation update procedures.
If you do start with an issue rather than an MR, use the Documentation template. Labels should include:
Backloguntil the work is scheduled for a milestone.
Noneuntil the work is scheduled for a milestone. In the issue description or comments, mention (
@username) the Technical Writer assigned to the group for awareness.
If an issue requires input from the development team before a Technical Writer can start work, it should follow the stage and group's issue lifecycle. For an example of an issue lifecyle, take a look at Plan Stage Issues.
The Technical Writing team is always working to improve the quality of the documentation. Specifically, we are working to implement topic types.
We are currently tracking updates to the Use GitLab section of the global navigation.
|Date||# of pages done||# of pages total||Percent complete|
|April 2022||161||420||38 %|
|October 2022||245||468||52 %|
The Technical Writing team hosts a Docs Hackathon twice a year. The Docs Hackathon is separate from the GitLab Hackathon.
We often create documentation issues for a Hackathon. These issues are typically based on results found when you run Vale against the documentation.
Run Vale against the full docset. Go to the GitLab repo and run:
find doc -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../results.txt
Create issues. You have a few options:
Ensure that the labels assigned to the issues match those in the
Doc cleanup issue template.
To assign an issue to a community contributor:
Seeking community contributionslabel.
/assign @usernamein a comment, where
@usernameis the contributor's handle.
Try to limit each contributor to no more than three issues at a time. You can assign another issue as soon as they've opened an MR for one of the issues they're already assigned.
When a community contributor opens a Hackathon merge request:
We use a Disqus integration for commenting and discussion on most pages on
docs.gitlab.com. Disqus is also used as a commenting tool on blog posts on
about.gitlab.com. There is an open issue discussing alternatives to Disqus.
We disable the Disqus integration on index and landing pages that contain lists of links. For example, Contributor and Development Docs has the comments attribute set to
The volume of comments is low at around one or two per month.
Technical writers are responsible for checking the
#docs-comments Slack channel regularly, and responding or routing comments to the Technical Writer assigned to the group, based on the page metadata.
docs.gitlab.com. Make sure it is not an index or landing page.
#docs-commentsSlack channel, review and triage the comment.
~docs-commentslabel to MRs or issues that you create in response to comments.
When working with issues or merge requests, the Technical Writing team uses labels to describe those issues' and merge requests' attributes (including the types of work being done).
The information about labels as described in this section supplements the contents of the Issues workflow page. To view a usage description of each of the labels in this section, see Labels in the GitLab interface.
Any issue or merge request for which a Technical Writer provides a measurable amount of work on (including content creation and reviews) must include the
Technical Writing label.
After adding the
Technical Writing label, we want to classify the type of effort we're contributing to the issue or merge request by adding an additional label from the following list:
documentation- Use this label if files in the
/docdirectory were added, changed, or removed.
UI text- If an issue has this label:
non-SUSlabel and the
feature::enhancementlabel, add a severity label (it should already have the
global nav item
release post item
development guidelines- See the Developer documentation for information about updating pages in the
Technical Writing Leadership
Depending on the issue or merge request, you may include one or more of the preceding labels with the issue or merge request, depending on its contents. There may be occasions when none of the preceding labels apply to the issue or merge request; in that case, having only the
Technical Writing label is enough.
If an issue/merge request has both the
Technical Writing and
labels, Technical Writers should add one of the following
to the issue/merge request on which they work:
To better communicate work status, the Technical Writers use the following labels to describe issues' statuses:
Note that these are team workflow labels. The Technical Writer who is doing
writing work will usually be the person adding the
tw::doing label, and the
Technical Writer doing the review will usually be changing it to the
tw::finished label (although external content submissions could have the
same Technical Writer using both the
tw::finished labels as
part of their content review).
The labels are used as follows:
Technical Writinglabel, as usual.
tw::doinglabel. In this case, work is everything that's required to finish the content, from creation through review. If a writer involved in the process stops working on the unfinished issue/MR, they remove the
tw::doinglabel (at least at the point of one work week of inactivity). Whenever work is restarted, the
tw::doinglabel is restored.
Note that the
tw::finished label is for indicating when a Technical Writer
is done with an issue/MR for which we're not doing the merge or closing the
issue. If the Technical Writing team is doing the merging/closing, the issue/MR
status overrides the scoped
tw label status, and there's no need to use the
If a Technical Writer is presented with an open issue or MR with a
tw::finished label that has more work required for it, the writer should
tw::doing scoped label to the issue/MR, and then continue with
the normal workflow process.