Knowledge Base
"How we document runbooks and repeatable fixes in Notion."
Why this exists
The half-life of undocumented knowledge at an agency is short. When the engineer who knows how to restart a payment queue leaves, that knowledge goes with them. We write runbooks so we don't have to search for answers while a client waits.
Operational Flow
Write immediately: Document non-obvious fixes (like env quirks or API limits) the moment you resolve them.
Use the template: Set a Title, Trigger, Steps (with exact shell commands), Gotchas, and Last Verified date.
Centralize storage: Put client-specific runbooks in the client's Notion workspace, and team runbooks in Kryft's Notion.
Link tickets: Link to the runbook in your Linear resolution notes when closing related bugs.
Review quarterly: Check runbooks every three months. Update or archive files older than six months.
Write for context-free readers: Assume the reader is skilled but has never touched this specific environment.
What good looks like
- A developer joins a project mid-sprint and restores a staging database using only the Notion runbook.
- A recurring cron failure has a runbook with the exact error log and the step-by-step fix.
- Outdated runbooks are cleaned up or updated during the quarterly review.
What NOT to do
- Don't store critical steps in Slack threads. Slack messages disappear and are hard to search.
- Don't write passive instructions. Write 'Run: fly pg restart' instead of 'the database should be restarted'.
- Don't skip the 'Last Verified' date. Undated instructions are untrustworthy.
- Don't hoard information. Being the only person who knows how to run a deploy is a liability.
A knowledge base only works if the team has the discipline to update it. Most agencies plan to write things down later, but their Notion spaces end up filled with empty onboarding templates. We have had incidents where the fix was known but undocumented, and the person who knew it was on a plane. That is an embarrassing and avoidable failure.
If you had to research a fix, write it down before moving on. The runbook doesn’t need to be long; it needs to be exact. Commands matter more than descriptions. The verification date is important because codebases drift. What worked for a database in February might fail in August. Spending fifteen minutes on updates keeps the documentation useful.