Bramble

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.

Bramble 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?

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.

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 Bramble, 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 Bramble, 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.

  • Bramble uses GitLab 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.

Suddenly remote quick boot handbook guide

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 Bramble’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.

Using GitLab to build and evolve a company handbook

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.

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.

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

The beauty of using a tool like Bramble 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 teams in the organization.
  2. Groups/teams/departments: Build the rest of the handbook out by teams e.g.

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 teams.

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.

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 Bramble. Team members are as likely to see merge requests put forth by founders 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).

Not just handbook-first… website-first is even more efficient

Where possible, it is even more efficient to post documentation directly to the website (about.brmbl.io, 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 Bramble 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 Bramble Handbook Usage.

Learn more about documentation

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

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

Return to the main all-remote page.