This page is meant to provide some guidance on writing workflow pages including creating new or updating existing workflows.
It is meant to be easy to read and quick to scan in the spirit of the guidance provided on this page.
While having information written down has many benefits, for people to find what they need, it needs to be well organized too.
Organization is particularly important in the workflows because often steps for a process only apply in some cases. Making it easier for a team member to follow a process while also allowing them to only read the necessary parts to complete a task is needed for efficiency.
Creating, updating, and improving workflows fits with [GitLab values]/handbook/values/) and emphasizes many of our operating principles and approaches including:
This very page came out of a discussion on increasing support efficiency.
Good workflows have:
For general writing practices including inclusive language and use of markdown, consider following the GitLab documentation guidelines.
Let's take the Support Time Off page as an example (even though it's not a workflow page, it's process related).
The original version organized the information by using number of days off as the "divider".
That's understandable, but difficult to scan which parts are relevant to an individual, because not all Support team members have PagerDuty shifts, or assigned tickets (think Support Ops). Additionally, some pieces duplicated company handbook information.
In a revision, the page was reorganized to focus on responsibilities so that team members could skip sections that are not relevant to them.
This is a small, but hopefully good example of how a difference in organizing the content can make it easier and more efficient for the reader.
When creating a new workflow, please keep the above guidelines in mind, and consider this process:
There is no specific template for a workflow (except the metadata noted below). Some possible places to start:
The following metadata and table of contents pieces should be at the top of every workflow page.
Notes:
subcategory
. All others must be filled in.---
layout: handbook-page-toc
title:
description:
category:
subcategory:
last-reviewed: YYYY-MM-DD
---
## On this page
{:.no_toc .hidden-md .hidden-lg}
- TOC
{:toc .hidden-md .hidden-lg}
## First heading