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.
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.
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 the same bits of data in perpetuity, creating a torturous loop of interruptions, meetings, and suboptimal knowledge transfers.
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.
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.
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 understand profoundly through intuition or empathy.
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.
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.
If you're looking to stand up a rudimentary handbook quickly, consider the Suddenly Remote Handbook. This is a free tool built by GitLab's Mike Terhar, and may be iterated on in the future.
The Getting Started section provides a step-by-step overview of launching the handbook, and there are several pre-filled sections based on GitLab's learnings that you're welcome to utilize, tweak, or cut.
The project that drives the sample rendering and starter template can be found here.
GitLab is a collaboration tool designed to help people work better together whether they are in the same location or spread across multiple time zones. Originally, GitLab let software developers collaborate on writing code and packaging it up into software applications. Today, GitLab has a wide range of capabilities used by people around the globe in all kinds of companies and roles.
You can learn more at GitLab's remote team solutions page.
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:
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. Tools like Almanac, Notion, and Guru can be used as well. 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.
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.
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 an operating principle 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.
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.
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.
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.
Where possible, it is even more efficient to post documentation directly to the website (about.gitlab.com, docs.gitlab.com) if customers, prospects or the wider community would benefit from the content. Marketers, product management and other content generators should challenge themselves to write content in a way that it can be a SSoT (single source of truth) for both external and internal audiences.
For example: if a topic is described on the public website, only add necessary commentary on that topic for internal GitLab audiences in the handbook with links to the SSoT on the public website.
Learn more about using handbook screenshots instead of creating a presentation in GitLab Handbook Usage.
Learn more about the importance of documentation in the GitLab resources below.
Complete all knowledge assessments in the Remote Work Foundation certification to receive the Remote Foundations Badge in GitLab Learn. If you have questions, please reach out to our Learning & Development team at learning@gitlab.com.
GitLab is one of the world's largest all-remote companies. We are 100% remote, with no company-owned offices anywhere on the planet. We have over 1,500 team members in more than 65 countries. The primary contributor to this article (Darren Murph, GitLab's Head of Remote) has over 15 years of experience working in and reporting on colocated companies, hybrid-remote companies, and all-remote companies of various scale.
Just as it is valid to ask if GitLab's product is any good, we want to be transparent about our expertise in the field of remote work.
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.
