Working in GitHub

Most companies scatter their work across a chat app, a wiki, a task tracker, a docs tool, and six people's memories. We try to keep it in one place. For us that place is GitHub: the code lives there, so does this handbook, the roadmap, and most of the decisions that shape the company. If it matters and it's writeable, it probably belongs in a repo, in the open. This is the mechanical side of how this handbook works and defaulting to open.

Why one place

When the work lives in one system, a new person can reconstruct how the company got here by reading, rather than by asking around and hoping someone remembers. Issues hold the discussion, pull requests hold the change and the reasoning, and the history holds the "why." A decision made in a disappearing chat message is one the company will have to make again in six months; a decision made in a pull request is one anyone can find later.

How we use it

• Issues are for thinking out loud. A problem, a proposal, a rough idea: open an issue, describe it, and let people poke at it in public. Half-formed and visible beats polished and private.
• Pull requests are how things change, whether the thing is code or a handbook page. You make the edit, explain why in the description, and it gets reviewed and discussed before it merges. The reasoning lives next to the change.
• Write the "why" down, in the PR description, the commit, the issue. The diff shows what changed; you're on the hook for why. Future readers, including future you, need the reasoning more than the mechanics.
• Public by default. Work happens in public repos unless there's a specific reason it can't (see what we keep private). Closing something should have to justify itself; opening it shouldn't.

New to working this way?

If GitHub has mostly been a code thing for you, using it to run a company can feel odd at first, and that's fine. You don't need to be a git wizard. The core loop is small: open an issue to raise something, open a pull request to change something, and say why in plain words. Ask in Discord if you get stuck; someone will happily walk you through it.