Handbook Usage & Principles

What is the Handbook?

The Sourcegraph Handbook is centralized documentation system for how we work. We are a handbook-first company because:

1. A written process is followed more closely and frequently than an informal one, which leads to more people and iterations to improve it.
2. We believe anyone can and should propose improvements to a written-down process. Learn how to propose an edit the handbook.
3. New teammates can onboard more quickly by reading our handbook to understand background information and processes.
4. When you go on vacation or to sleep, you can relax knowing that nobody will be blocked while you’re not working. They can rely on the handbook.

What does it mean to be Handbook-first?

Being handbook-first means using the handbook as the source of truth for answers and processes.

To be handbook-first, we must:

• Rely on the handbook being a reliable source of truth: accurate and up-to-date.
• Default to the handbook when looking for information about a business process or policy, not just when we read about it the first time, but as a habit every time because we expect it to keep evolving.
• Share responsibility for keeping the handbook accurate and up-to-date. If you notice something is missing or inaccurate, it is your responsibility to propose a change. This takes a lot more time than just doing things and not writing things down. But being handbook-first is worth it because it yields better processes and helps us work together efficiently as we grow.

Handbook Usage

• Most content in this handbook is meant to help rather than being absolute rules (unless stated).
• For any process to be in force, it must be documented in the handbook. A Google Doc or pending PR to the handbook is not sufficient because using those reduces the effectiveness of the handbook as a trusted source of knowledge. Further, if you never need to merge your change to bring it into force, we aren’t encouraging making small, iterative improvements. This is a rule required for us to truly be a handbook-first company.
• Whenever possible, link to the Handbook rather than providing a written-out answer to a teammate’s question. If you ask a question and someone answers with a link to the handbook, they are doing so because the handbook has the best answer for your question.
  • Similarly, if someone replies to a question with a newly typed-out answer that differs from what’s in the handbook, gently ask them to either follow what’s in the handbook or propose an edit to the handbook.
• If what you’re looking for isn’t answered in the handbook, it’s likely that someone else will have the same question in the future. Document the answer by updating the handbook to help everyone else, or clearly pass along the responsibility to do so to someone else (“Who will document this?”).
• Related to the above, resist the temptation to improve something at the same time you document it. As a first step, make a PR to document things as you know them to be today and then create another PR to add improvements. By separating these two steps, you avoid a situation where a proposal and improvement blocks documenting what people need to know today.
• The handbook documents what we do right now. It doesn’t describe the ideal practices we hope to follow in the future, or outdated practices we followed in the past.
• Announce important changes in the appropriate channels. Ensure everyone who needs to be aware of the change is made aware.
• Use PRs to discuss change proposals to the handbook whenever possible (an exception, for example, might be when discussing non-public information that might lead to a handbook update.) Using a Google Doc, Slack, etc. instead can be easy to miss existing (even conflicting) content and also makes it hard to follow the discussion since it is in multiple places. Getting to a PR also more quickly makes it easier to discover these and for others to contribute cross-links or highlight duplicated/conflicting content.
  • Note: In some cases, it might make sense to start with an RFC. In any case, before changes are implemented, they must be documented in the handbook.
• Follow the Sourcegraph content guidelines for consistent voice and style.
• Follow the Handbook Content Best Practices for help with structuring your content, and deciding where it should live.

Why do we use Git? Why not a wiki or Google Docs?

The handbook consists of Markdown files in the Git repository at github.com/sourcegraph/handbook. Being handbook-first means the Handbook must be kept up to date. There are several benefits in using Git over another format:

1. Many handbook changes require updating references and mentions across multiple pages. In wikis and Google Docs, there is no easy way to propose a group of changes to multiple sections or pages, which means people making and reviewing edits can easily miss other places that need to be updated. This format allows grouped multi-page changes and collaboration. This is more complicated than wikis or Google Docs, but we commit to help every teammate learn how to edit this handbook.
2. Many handbook changes are collaborative and need to be reviewed, revised, and commented on by other teammates. Git makes this possible, with comments and code reviews. Wikis don’t make this easy or possible, and Google Docs has very limited review and no revision capabilities.

Handbook Support

Handbook feedback

We’re constantly working to make the Handbook better. Is it easy to use? Do you find what you’re looking for? Let us know here.