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

The importance of a handbook-first approach to documentation

On this page

Introduction

A handbook-first approach to documentation is sneakily vital to a well-run business. While it feels skippable — inefficient, even — the outsized benefits of intentionally writing down and organizing process, culture, and solutions are staggering. Conversely, avoiding structured documentation is the best way to instill a low-level sense of chaos and confusion that hampers growth across the board.

GitLab is intentional about documenting in a manner that creates a single source of truth. It operates handbook-first, and in valuing transparency, makes its handbook publicly accessible to all.

Terminology (documentation, handbook-first, single source of truth)

While the term documentation often refers to the process of writing something down after a given event, this page details a more meaningful approach. Documentation should occur first, in a structured and organized way, before being disseminated. (E.g. Document the solution first, then announce via Slack or email.)

The goal isn't to create a culture of documenting for the sake of documenting; rather, to create an environment where net new solutions are documented in a universally accessible handbook before dissemination, and iterations are made to the universally recognized single source of truth. Each team member must approach documentation the same way, much like an editorial team adheres to a style guide.

Why does handbook-first documentation matter?

GitLab all-remote handbook-first documentation illustration

In early-stage startups, it's particularly tempting to avoid a documentation strategy. With only a few team members, it's feasible to keep everyone informed via meetings, Slack, or email threads. Long-term, this oversight becomes increasingly harmful.

As a team scales, the need for documentation increases in parallel with the cost of not doing it. Said another way, implementing a documentation strategy becomes more difficult — yet more vital — as a company ages and matures.

Documentation is rarely placed on the same pedestal with metrics such as sales and client retention during a company's formative years, but it deserves to be. The difference between a well-documented company and one that eschews a handbook is stark.

A handbook-first organization is home to team members who benefit from having a single source of truth to lean on. This type of organization is able to operate with almost supernatural efficiency. An organization that does not put concerted effort into structured documentation has no choice but to watch its team members ask and re-ask for same bits of data in perpetuity, creating a torturous loop of interruptions, meetings, and suboptimal knowledge transfers.

Start now

A top concern from established colocated or hybrid-remote organizations who wish to transition to all-remote is their tardiness in creating a company handbook. This sentiment is also shared by companies that maintain separate offices — which are remote to each other — who long to lay the groundwork necessary for teams to collaborate seamlessly.

It's important not to let hindsight thwart progress in the here and now. While an ideal time to begin a company handbook is at inception, the next best time is today.

Let your Slack or chat messages expire quickly

At GitLab, only 90 days of Slack activity is retained. After that, it's gone. This is intentional, as it prevents Slack as being useful as a tool for managing projects end-to-end. Slack, Microsoft Teams, and similar tools are instant messaging platforms, which may work to the detriment of a truly asynchronous culture.

Leaders who are serious about ensuring that their team can rely on a single source of truth will be ruthless when it comes to instant message retention. If team members know that they can search their instant message history for updates on a given project, there is no motivation to document progress in a place that is universally accessible. This creates massive knowledge gaps and further splinters communication, alignment, and understanding throughout an organization.

A limited retention policy acts as a forcing function. It nudges team members to discuss work matters in a location that is directly tied to the ultimate single source of truth. At GitLab, all work, process, and policies are documented in the handbook.

To get there, discussions begin in GitLab Issues and/or Merge Requests — not in Slack. This ensures that whatever is merged into the handbook has a proper trail, full of context and universally accessible.

Instant messaging tools are difficult to add people to a conversation, and all work history is left in that program, with no context following the work to where it eventually ends up.

It's difficult to rally an organization to only use Slack for informal communication, but it's worth the effort. Otherwise, you ensure a tortuous pattern of people pinging people for updates and snippets of information, adding further fuel to the chaotic fire that is synchronous workflows.

Don't get overwhelmed

There's a very real fear that committing to a handbook, and instilling a culture of documentation, is too tall a task to actually accomplish. The goal should not be to complete the handbook before ever announcing its existence to the company.

For established organizations, the trick is to apply iteration to the challenge of standing up a handbook within a company. Put the proper infrastructure in place (which we'll cover below), and begin documenting process after process, one at a time. Building a handbook well after a firm's infancy is tough, as you're changing both process and culture while operating a business at scale. However, leaders can manage expectations to make the handbook's insertion easier to grok.

Documentation is never finished

Handbooks, and the documentation that creates them, are never finished. They are evolving, living entities, and it may take months or years to feel even remotely comprehensive.

Resist the urge to abandon documentation plans when crisis hits. The most powerful documentation is that which is derived from failure. A lesson learned provides a vital roadmap of what to avoid, and how to operate better, in the future.

Tools for building a handbook

A common belief is that a company wiki can serve as a handbook, but the reality is that wikis do not scale. They are designed to be updated by a select few, which creates several issues. One, content frequently falls out of date, which triggers a companywide belief that the information cannot be trusted without personally confirming with another human (and in turn, injecting inefficiency into the process of self-learning).

Two, it creates class segmentation — those entrusted to update the wiki, and those who are not yet wise or elite enough to do so.

Wikis are also highly siloed. They do not support proposals which touch multiple parts of multiple pages.

GitLab (the company) uses GitLab (the product) to maintain and evolve its handbook, and other organizations regardless of size can do likewise. By leveraging distributed version control, anyone in the company (and even outside of the company) is empowered to put forth proposals for improvement.

Empower the entire team to evolve the handbook

Crucially, GitLab merge requests split the role of submitter and approver. There is no harm in opening your handbook up to proposals, as code owners and DRIs (directly responsible individual) are ultimately responsible for reviewing each proposal and merging or editing and merging.

This enables anyone at the company, even those who have just joined, to propose changes and feel immediately invested in a company's culture of documentation.

Examples that showcase the power of distributed version control in handbook documentation:

  1. In this merge request, only a portion of the initial proposal was agreed upon and merged into GitLab's handbook. However, this ensured that all pertinent parties had a voice. This also documents the thought process that went into the eventual documentation, such that context is in place for anyone to understand why these changes were made, and when.
  2. By empowering all team members to make proposals, you enable new hires to offer up fresh perspective that can benefit the company. This merge request is an example of a new hire sharing a proposal to strengthen GitLab's Onboarding Buddy checklist, and then her buddy made a proposal which was eventually merged.
  3. This merge request was proposed by someone still in the onboarding phase at GitLab. The discussion threads offer visibility into how learning happens, how iteration shapes proposals, and how everyone can contribute to the handbook's evolution.

Creating a home for a single source of truth (SSoT)

The beauty of using a tool like GitLab to build and evolve a company handbook is that you don't have to have the full table of contents mapped out in advance. Consider the following as an initial guide for top-level organization, but don't hesitate to deviate based on the size, scope, and needs of your firm.

  1. Company: This section houses policies, values, KPIs/OKRs, and cultural principles that apply to most or all departments in the organization.
  2. Groups/departments: Build the rest of the handbook out by departments (e.g. People, Engineering, Marketing, Sales, Finance, Product, Legal). This orients the reader with context of which group it primarily impacts, but does not preclude team members from one department from making handbook proposals to other departments.

Most sections will be blank to begin with, and that's OK. Apply the spirit of iteration to documentation. Rather than judging a section for how light it is, praise a contributor for making it marginally better than it was prior.

Make handbook-first documentation a value

The trick to ensuring a handbook grows continually is to instill it as a value. Team members should recognize that any answer or solution that isn't yet documented, should be documented immediately.

In the GitLab Unfiltered video above, Darren (Head of Remote, GitLab) and Gabe (Senior Product Manager, GitLab) talk on the topic of going slow to go fast, as well as the importance of a "handbook-first" approach to companywide documentation.

I think documentation has to be instilled as a value. It has to start there, and the whole leadership team in an organization has to be onboard.

All of leadership needs to understand the importance of documentation — not just with lip service. A true, genuine understanding of its value. If they truly understand the value of it, they'll emanate that to their direct reports.

For companies looking to transition to fully remote, a helpful step for leadership is to say: "OK, we're going to be remote-first as a start." This means that a company in transition would optimize everything in its physical office space to be remote-first. Instead of optimizing conference rooms with lots of tables, for instance, you have each employee sit in their own office and wear headsets all day. This is how you prevent remote employees from feeling disconnected and isolated.

This is going slow to go fast. Lots of energy up front — you go slow — but that accelerates things dramatically a year or so down the road. — Gabe W., Senior Product Manager, GitLab

Write things down is a sub-value of Efficiency at GitLab. Team members are as likely to see merge requests put forth by e-group members as they are new hires.

Empowering the entire company to propose changes creates widespread autonomy and agency. This generates a shared responsibility to maintain the pace of documentation through a pay-it-forward mentality.

Designate scribes or a handbook editor team

Ideally, everyone feels as if they are a contributing member of a handbook's evolution. This is easier to foster when you instill documentation as a value at an early stage. For scaled companies adding a handbook many years after inception, consider hiring dedicated scribes that sit on each team.

Former journalists are ideal for this type of work, as it goes well beyond transcription. Documenting notes during meetings, and converting them from Google Docs to handbook, requires a knack for storytelling as well as an understanding of what's important and what context should be added.

Consider investing in a handbook editor team that ensures the engineering framework is up to date, and that code owners are notified whenever pages go too long without an update.

These individuals come at a cost; however, this cost pales in comparison to the investment companies will make in perpetuity when paying team members to sit in meetings extracting answers that could've been documented years before.

This says nothing of the cost of institutional knowledge. Documented answers are easily ingested by new hires, including information that was documented by team members who have since moved elsewhere in their career journey (example above).

Make it public

To whatever degree you legally can, consider making your company handbook public. Not only does GitLab do this, but outfits such as Glitch, MarsBased, and Basecamp do as well. Public handbooks lead to accountability. It's easier to let an internal wiki rot than it is a handbook which is open to the world.

Too, this allows the public as well as companies in your industry to replicate processes and make suggestions for improvement. Remember, this doesn't mean that those who provide input have a right to feel heard or considered; it simply opens wide the gate for improvements you'd never consider in your own bubble.

This also creates a more welcoming environment for applicants and new hires. By sharing processes, culture, and strategy, your hiring teams are likely to field inbounds which are more qualified, put forth by individuals who have already investigated your company and believe that they align with your goals and mission.

Learn more about documentation

Learn more about the importance of documentation in the GitLab resources below.

  1. Documentation handbook section
  2. Documentation style guide
  3. Documentation guidelines
  4. Scaling by documenting

Contribute your lessons

Approaching documentation with unwavering intention is a challenge for all companies. If you or your organization has an experience that would benefit the greater world, consider creating a merge request and adding a contribution to this page.

Return to the main all-remote page.