GitLab's handbook-first approach to internal documentation

GitLab is known for running much of the company from a public handbook at handbook.gitlab.com. Most of it is readable by anyone, and its pages carry "View page source" and "Edit this page" links. This teardown looks at the rules GitLab publishes for using it. It is not a Steperly customer story: we're not affiliated with GitLab, and everything below comes from their public handbook, linked in the sources.

Most teams can't copy GitLab wholesale: it is a large, all-remote company with engineering tooling built around merge requests. The underlying habits, though, work at almost any size. We'll cover what GitLab does, why it works, and a version a ten-person team can start this month.

What "handbook first" means

GitLab's handbook usage page describes a simple flow for changing how the company works:

1. A process problem comes up, often in an issue or chat.
2. Someone proposes a fix as a merge request to the handbook.
3. Once merged, the change is announced by linking to the diff, with bigger changes posted in a company-wide Slack channel.

The rule underneath is strict: communicate a proposed change only through a change to the handbook, not a presentation, email, or chat message. Even when a meeting needs a live Google Doc, the handbook says the doc's first item should be the URL of the handbook page the content will move to.

The page also says what the handbook is: not what the company hopes to do or did months ago, but what it does now.

It is what we do right now.

GitLab goes a step further with "public handbook first": anything that can be shared publicly goes in the public handbook, and only internal-only information lives in a separate internal one.

Why it's worth the extra effort

GitLab doesn't pretend this is the easy path. The handbook admits that documenting first takes more time up front, because you have to find where a change fits and sometimes restructure the page around it. It argues the time comes back later, and compares the practice to writing tests for software.

The same page quotes co-founder Sid Sijbrandij, from an INSEAD case-study interview, describing information as bricks. In his telling, most companies hand people bricks through Slack, email, and meetings, and everyone builds their own slightly different house. At GitLab, everyone adds to one house.

Every piece of information is a brick.

Why it works: chat and slide decks are easy to send and hard to find later. A change made in the handbook can be found, linked, and built on by the next person. Duplication goes away because there's only one place to look.

The everyday habits that keep it alive

A handbook only stays current if people use it during normal work. GitLab spells out small, repeatable behaviors, several phrased as gentle reminders teammates can say to each other:

The handbook also sets a tone for these reminders. It says nobody knows the entire handbook, and that answering a question with a link is meant to help, not to scold.

How GitLab keeps a huge handbook usable

A handbook-first company produces a lot of pages. GitLab's guidelines focus on keeping them findable and trustworthy:

• One source of truth. Instead of repeating content, cross-link it. If you copy something, remove the original and replace it with a link.
• Organized by function and result, so every page has a location and an owner. GitLab says not to keep separate structures for onboarding materials, how-tos, or videos; put content where the work lives and link to it from elsewhere.
• Avoid unstructured formats such as playbooks, FAQ pages, link lists, and glossaries, which the handbook calls very hard to keep up to date. Put the answer in the most relevant place instead.
• Short pages and descriptive headings, because new employees cite the amount of information as their biggest onboarding challenge.
• Add the why. Explaining the business goal behind a process makes it easier to change later, since you can check whether the reason still holds.
• Small, fast changes. Make small merge requests and aim to merge the same day. If you need to move content, do the move in its own change.
• Contributable diagrams, such as Mermaid or PlantUML in Markdown, over uploaded images that are harder for others to edit.

Making changes visible

A single source of truth only helps if people notice when it changes. GitLab handles this in a few ways, all described on the same handbook page:

• Announce with the diff. Process changes are communicated by linking to the merged change, which shows the before and after, rather than restating the new rule in a message.
• Tiered announcements. Major changes go to a company-wide channel; medium ones go to a dedicated handbook channel with a one-line summary. Anyone can join that channel to follow changes.
• Clear titles. Contributors are asked to write change titles that let someone understand the content quickly, since keeping up with changes is hard.
• Label experiments. If a process is a limited test with some users, it still goes in the handbook, marked as a test, and the note comes off when the test ends.

Why it works: the announcement points back to the source instead of competing with it. Nobody has to wonder whether the Slack message or the page is correct, because the message is just a link to the page.

The detail most teams miss: screenshot the handbook

One section is easy to skip and very practical. For evergreen material such as training, GitLab says to screenshot the handbook instead of creating a presentation, and to link to the pages shown rather than copying content into slides. The reasons it gives: you only maintain one thing, the content stays current, viewers see that the answer lives in the handbook, and they learn its structure so they can find things later. It even admits the result will look less polished, and argues the advantages outweigh that.

This is the opposite of how most teams train people. They build a deck once, the product or process changes, and the deck quietly goes stale.

How to apply this on a small team

You don't need merge requests or a public handbook. You need one place, one rule, and a few habits. A version for a ten-person team:

1. Pick one home for "how we work." A wiki, Notion, or a docs folder all work. What matters is that there's exactly one.
2. Adopt the rule: change the doc, then announce the link. No process changes by Slack message alone. If it isn't written down, it hasn't changed.
3. Answer repeat questions with a link, and write the page when there isn't one. Make "Who will document this?" a normal thing to say.
4. Write procedures as steps with real screenshots. A standard operating procedure is easier to follow and update when each step shows the actual screen. Start from our free SOP template generator, or record the task once and turn it into steps with video to guide.
5. Train from the docs, not from slides. Walk new hires through the live pages. If you need visuals, capture them from the docs and mark them up with the screenshot annotator instead of rebuilding them in a deck.
6. Give every page an owner and a why. One name per page, one sentence on the goal. Review the most-used pages whenever the underlying tool or process changes.
7. Keep changes small and frequent. Ten one-line fixes a week beat a quarterly docs cleanup that never gets scheduled.

Where handbook-first is hard

It is worth being honest about the costs, as GitLab is. Documenting first is slower in the moment, and it only works if leaders model it; GitLab lists holding teams accountable for being handbook first as an explicit expectation for people leaders. It also assumes a culture comfortable with written, asynchronous decisions. A team that runs on hallway conversations will need to make the shift deliberately, starting with the processes that cause the most repeated questions.

Start there: pick the three processes new hires ask about most, write them down with screenshots, and send links instead of answers for a month. That's handbook first at a size you can sustain. For more on structuring internal docs, see our page on employee training documentation.