---
layout: markdown_page
title: "The importance of a handbook-first approach to documentation"
twitter_image: "/images/opengraph/all-remote.jpg"
---
## On this page
{:.no_toc}
- TOC
{:toc}
## Introduction
A [handbook-first](/handbook/handbook-usage/#why-handbook-first) approach to documentation is [sneakily vital](/company/culture/all-remote/management/#scaling-by-documenting) to a well-run business. While it feels skippable — inefficient, even — the outsized benefits of intentionally writing down and organizing process, [culture](/company/culture/all-remote/building-culture/), and solutions are staggering. Conversely, *avoiding* structured documentation is the best way to instill a low-level sense of [chaos and confusion](/handbook/values/#five-dysfunctions) that hampers growth across the board.
GitLab is intentional about documenting in a manner that creates a [single source of truth](/handbook/values/#single-source-of-truth). It operates [handbook-first](/handbook/handbook-usage/#why-handbook-first), and in valuing [transparency](/handbook/values/#transparency), makes its handbook [publicly accessible to all](/handbook/).
## 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](/handbook/values/#single-source-of-truth). Each team member must approach documentation the same way, much like an editorial team adheres to a [style guide](/handbook/style-guide/).
## Why does handbook-first documentation matter?
{: .shadow.medium.center}
In early-stage startups, it's particularly tempting to avoid a [documentation strategy](/handbook/handbook-usage/#why-handbook-first). 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](/company/culture/all-remote/self-service/). 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](/handbook/values/#single-source-of-truth) to lean on. This type of organization is able to operate with almost supernatural [efficiency](/handbook/values/#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](/company/culture/all-remote/stages/) or [hybrid-remote](/company/culture/all-remote/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](/handbook/communication/#slack). 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](/company/culture/all-remote/asynchronous/).
Leaders who are serious about ensuring that their team can rely on a [single source of truth](https://docs.gitlab.com/ee/development/documentation/styleguide.html#documentation-is-the-single-source-of-truth-ssot) 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](/company/culture/all-remote/asynchronous/#plugging-the-knowledge-leak) 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](/handbook/).
To get there, [discussions begin](/blog/2016/03/03/start-with-an-issue/) in [GitLab Issues](https://docs.gitlab.com/ee/user/project/issues/) and/or [Merge Requests](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) — not in Slack. This ensures that whatever is merged into the handbook has a proper trail, full of [context](/company/culture/all-remote/effective-communication/#understanding-low-context-communication) 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](/company/culture/all-remote/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](/company/culture/all-remote/asynchronous/#mental-health) 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](/handbook/values/#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](/handbook/handbook-usage/#wiki-handbooks-dont-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](/company/culture/all-remote/self-service/)).
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](/company/history/)) uses GitLab (the [product](/stages-devops-lifecycle/)) to maintain and evolve its handbook, and other organizations regardless of size can do likewise. By leveraging [distributed version control](/product/source-code-management/), 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](/handbook/people-group/directly-responsible-individuals/)) 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](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/29227), 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](/company/culture/all-remote/effective-communication/#understanding-low-context-communication) is in place for anyone to understand why these changes were made, and when.
1. 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](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/29045/) is an example of a new hire sharing a proposal to strengthen GitLab's [Onboarding Buddy](/handbook/general-onboarding/onboarding-buddies/) checklist, and then her buddy made a proposal which was eventually merged.
1. This [merge request](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848) was proposed by someone still in the onboarding phase at GitLab. The discussion threads offer visibility into how learning happens, how [iteration](/handbook/values/#iteration) shapes proposals, and how [everyone can contribute](/company/strategy/#why) to the handbook's evolution.
## Creating a home for a single source of truth (SSoT)
The beauty of using a tool like [GitLab](/product/) 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](/handbook/values/), [KPIs](/handbook/ceo/kpis/)/[OKRs](/company/okrs/), and [cultural principles](/company/culture/) 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](/handbook/#people-group), [Engineering](/handbook/#engineering), [Marketing](/handbook/#marketing), [Sales](/handbook/#sales), [Finance](/handbook/#finance), [Product](/handbook/#product), [Legal](/handbook/#legal)). This orients the reader with *[context](/company/culture/all-remote/effective-communication/#understanding-low-context-communication)* of which group it primarily impacts, but [does not preclude](/handbook/values/#short-toes) team members from one department from making handbook [proposals](/handbook/values/#make-a-proposal) to other departments.
Most sections will be blank to begin with, and that's OK. Apply the spirit of [iteration](/handbook/values/#iteration) to documentation. Rather than judging a section for how light it is, praise a contributor for making it [marginally better](/handbook/values/#minimum-viable-change-mvc) 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](/company/culture/all-remote/self-service/#paying-it-forward).
*In the [GitLab Unfiltered](https://www.youtube.com/channel/UCMtZ0sc1HHNtGGWZFDRTh5A) 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](/handbook/handbook-usage/#why-handbook-first)" approach to companywide documentation.*
> I think [documentation](/company/culture/all-remote/management/#scaling-by-documenting) has to be [instilled as a value](/handbook/values/#write-things-down). It has to start there, and the whole leadership team in an organization has to be onboard.
>
> All of [leadership](/handbook/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](/company/culture/all-remote/hybrid-remote/#disadvantages-to-hybrid-remote).
>
> 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.](https://gitlab.com/gweaver), Senior Product Manager, GitLab*
[Write things down](/handbook/values/#write-things-down) is a sub-value of [Efficiency](/handbook/values/#efficiency) at GitLab. Team members are as likely to see merge requests [put forth](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36397) by [e-group](/handbook/leadership/#e-group) members as they are [new hires](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848).
Empowering the entire company to propose changes creates widespread autonomy and [agency](/handbook/values/#give-agency). This generates a shared responsibility to maintain the pace of documentation through a [pay-it-forward mentality](/company/culture/all-remote/self-service/#paying-it-forward).
## 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](/company/culture/all-remote/scaling/) 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](/handbook/communication/#external-communication) during [meetings](/company/culture/all-remote/meetings/), and converting them from [Google Docs](/handbook/communication/#google-docs) to [handbook](/handbook/handbook-usage/#why-handbook-first), requires a knack for storytelling as well as an understanding of what's important and what [context](/company/culture/all-remote/effective-communication/#understanding-low-context-communication) 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 is extremely well-written and communicates the nuanced benefits as well as caveats of writing for business communication.
I added the original section for low-context communications in the handbook. Really excited you’ve unpacked that with such clarity and depth.
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](/company/culture/all-remote/hiring/#make-your-strategy-public). Not only does GitLab do this, but outfits such as [Glitch](https://handbook.glitch.me/), [MarsBased](https://github.com/MarsBased/handbook), and [Basecamp](https://basecamp.com/handbook) 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](/handbook/people-group/directly-responsible-individuals/#empowering-dris-no-explanation-needed); 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](/jobs/faq/#whats-it-like-to-work-at-gitlab) processes, culture, and strategy, your [hiring teams](/company/culture/all-remote/hiring/) 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](/company/strategy/).
## Learn more about documentation
Learn more about the importance of documentation in the GitLab resources below.
1. [Documentation handbook section](/handbook/documentation/)
2. [Documentation style guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html)
3. [Documentation guidelines](https://docs.gitlab.com/ee/development/documentation/)
4. [Scaling by documenting](/company/culture/all-remote/management/#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](https://docs.gitlab.com/ee/user/project/merge_requests/) and adding a contribution to this page.
Return to the main [all-remote page](/company/culture/all-remote/).