Skip to content

become handbook-first

Warren Gifford requested to merge handbook-first into master

Created by: sqs

As part of our goal to become handbook-first, this moves Markdown documents that are not related to the code or product from the sourcegraph repo here. It also adds new doc pages for each of our teams that they will maintain. Keeping all company, handbook, and process documentation in this repository (and deploying it to about.sourcegraph.com not docs.sourcegraph.com) makes it easier for everyone to contribute, allows us to render information more nicely on about.sourcegraph.com, and cleanly separates docs that are tied to a specific sourcegraph repo commit vs. docs that are not.

Preview: https://deploy-preview-300--sourcegraph.netlify.com/handbook

Related: https://github.com/sourcegraph/sourcegraph/pull/6402

Deployment plan

I want to deploy this soon even before it's "done" or reviewed because it will be much easier for others to contribute if it's on master. My plan is:

  • Set up Netlify to proxy https://about.sourcegraph.com/{handbook,direction,retrospectives,company,community}/* to a docsite server that renders this content for the handbook (and those other directories, which are related). (You can preview this at https://deploy-preview-300--sourcegraph.netlify.com/handbook.)
  • Set up redirects from https://docs.sourcegraph.com for all documents moved to this repository (eg https://docs.sourcegraph.com/dev/roadmap -> https://about.sourcegraph.com/direction).

My estimate is that this will be ready by Fri morning PST.

When the content is closer to being "done" (obviously it's always going to be changing, but I mean when we have no obvious "TODOs" or gaps in the content), I will add a link in the https://about.sourcegraph.com footer to the handbook. Until then, the only way to find the handbook content will be (1) directly navigating to the URL or (2) following a redirect from an old docs.sourcegraph.com page that was moved into the handbook.

Merge request reports