Editing the handbook

Every Sourcegraph teammate will be editing the Sourcegraph handbook frequently to keep information up-to-date and participate in important changes in the company. This guide helps everyone learn how to edit the handbook.

The handbook consists of Markdown files in the Git repository at github.com/sourcegraph/handbook. (Why not a wiki or Google Docs?)

How to get help

We don’t expect everyone on the team to figure this out on their own. Other teammates are happy to help!

  • Any engineer at Sourcegraph can help. (The code that engineers write at Sourcegraph also consists of files in a Git repository, so engineers are very familiar with making these kinds of edits.)
  • Teammates who have already made a handbook change can help.
  • Handbook support: Ask the @handbook-support group in Slack (formerly called “handbook heroes”), including @aharvey, @virginia, @ines, @jyavorska, @marybelzer, and @jean, for handbook help (via DM, #handbook, or #any-question). They volunteered to help anyone with anything handbook-related! If you too want to be part of handbook support, simply edit this page, add your name to the list and ping @handbook-support in the #handbook channel to inform them
  • Ask in #handbook: “Who can screen-share with me to help me make an edit to the handbook?”
  • Don’t be afraid of breaking anything! It is very easy for any engineer on the team to roll back to the previous version of the handbook if you make a mistake.

High-Level Walkthrough

Basics

Editing

Editing the Handbook Flow

Troubleshooting & Tools

Handbook feedback

We’re constantly iterating on what the best version of our Sourcegraph handbook might look like. Is it easy to use? Do you find what you’re looking for? Let us know here.