Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Technical Writing workflows

This document explains the workflows of the Technical Writing team.

These processes work in conjunction with the Product development flow, Product designer workflow, and Engineering workflow, and the broader information about contributing to GitLab found in PROCESS.md.

Documentation authoring and review

These processes are open to all GitLab contributors, so they are documented within GitLab's documentation itself.

See the Documentation process page.

UI text

Planning and authoring

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:

MR Reviews

Once the merge request is created, all changes and additions to text in the UI must be reviewed by the Technical Writer. 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.

Resources

Technical writers should familiarize themselves with these Pajamas Design System pages, use them when working with UI Copy, and contribute improvements to them if possible:

Additional information about composing and reviewing UI text:

Release posts

The technical writer for each stage group is a reviewer of their group's feature blocks authored by the Product Manager.

For each release, a single technical writer is also assigned to the Release Post Structural Check.

Workflow labels

Labels are described in the Development documentation Issues workflow page.