About This Handbook

This handbook is a living document — it will evolve as the lab grows and as we figure out what works. I'll be honest: I have no clue how to run a lab aside from what I've seen and heard does and doesn't work. This handbook is part of a journey to facilitate the best lab environment I can, for its members and for the research, and I want it to be something we build together.

That means every lab member is expected to contribute. If you find something out of date, poorly described, or missing, fix it. If you disagree with something, bring it up — in the #lab-handbook channel on Slack, in a 1-on-1, or in a PR comment. The handbook should reflect how we actually work, not how I imagined we would work when I wrote the first draft.

How to Make Changes

The handbook is an MkDocs site hosted on GitHub Pages. The source files live in the Lab-Handbook repository on GitHub — each page is a markdown file in the docs/ folder, and the site structure is defined in mkdocs.yml.

To make a change:

  1. Create a branch and edit the relevant markdown file(s).
  2. If you're adding a new page, add it to both the docs/ folder and the nav section of mkdocs.yml — otherwise it won't show up on the site.
  3. Open a pull request.
    1. Request Levensteinlab/lab-members as reviewers (this also sends a notification to #lab-handbook on Slack).
  4. Once at least one person has reviewed and approved your PR, it can be merged.

If you're not sure how to do any of this, see the basic GitHub tutorial or ask in #lab-handbook. Your first contribution is part of onboarding — you should have made at least one improvement to the handbook by the time you complete onboarding.

Reviewing Changes

When a pull request is opened, all lab members are requested as reviewers. You'll get an email notification and a message in the #lab-handbook channel. Only one person needs to approve a PR, but the notification is a prompt for everyone to look over the changes. So:

  1. When you get this notification, go look over the changes.
  2. If no one else has approved the PR yet, please approve it.

This is how we keep the handbook accurate and up to date as a team.