internal-docs

Files (7)

• README.md
• SKILL.md
• evals.json
• knowledge-management.md · references/
• post-mortems.md · references/
• rfcs-and-design-docs.md · references/
• runbooks.md · references/

SKILL.md (first lines)

## Key principles

1. **Write for the reader, not the writer** - Every document exists to transfer
   knowledge to someone else. Identify who will read it (decision-makers, on-call
   engineers, new hires) and structure for their needs, not your thought process.

2. **Decisions over descriptions** - The most valuable internal docs capture the
   "why" behind choices. A design doc that only describes the solution without
   explaining alternatives considered and tradeoffs made is incomplete.

3. **Actionability is everything** - A runbook that says "investigate the issue"
   is worthless. A post-mortem without concrete action items is theater. Every
   document should leave the reader knowing exactly what to do next.

4. **Living documents decay** - Docs that aren't maintained become dangerous.
   Every document needs an owner and a review cadence, or it should be marked
   with an explicit expiration date.

5. **Structure enables skimming** - Engineers don't read docs linearly. Use
   headers, TL;DRs, tables, and callouts so readers can find what they need
   in under 30 seconds.

---

## Core concepts

Internal docs fall into four categories, each with a distinct lifecycle and audience:

**Decision documents** (RFCs, design docs, ADRs) propose a change, gather feedback,
and record the final decision. They flow through draft, review, approved/rejected
states. The audience is peers and stakeholders who need to evaluate the proposal.
See `references/rfcs-and-design-docs.md`.

**Incident documents** (post-mortems, incident reviews) are written after something
goes wrong. They reconstruct the timeline, identify root causes, and produce action
items. The audience is the broader engineering org learning from failure. Blamelessness
is non-negotiable. See `references/post-mortems.md`.

**Operational documents** (runbooks, playbooks, SOPs) provide step-by-step procedures
for recurring tasks or incident response. The audience is the on-call engineer at
3 AM who needs to fix something fast. See `references/runbooks.md`.

**Knowledge documents** (wikis, guides, onboarding docs, team pages) preserve
institutional knowledge. The audience varies but typically includes new team members
and cross-team collaborators. See `references/knowledge-management.md`.

---

## Common tasks

### Draft an RFC

An RFC proposes a significant technical change and invites structured feedback.
Use this template structure:

```markdown
# RFC: <Title>

**Author:** <name>  **Status:** Draft | In Review | Approved | Rejected
**Created:** <date>  **Last updated:** <date>
**Reviewers:** <list>  **Decision deadline:** <date>

## TL;DR
<2-3 sentences: what you propose and why>

## Motivation
<What problem does this solve? Why now? What happens if we do nothing?>

## Proposal
<The detailed solution. Include diagrams, data models, API contracts as needed.>

## Alternatives considered
<At least 2 alternatives with honest pros/cons for each>

## Tradeoffs and risks
<What are we giving up? What could go wrong? How do we mitigate?>

## Rollout plan
<How will this be implemented incrementally? Feature flags? Migration?>

## Open questions
<Unresolved items that need input from reviewers>
```

> Always include at least two genuine alternatives. A single-option RFC signals
> the decision was made before the review process started.

### Write a post-mortem

Post-mortems extract organizational learning from incidents. Follow a blameless
approach - focus on systems and processes, never on individuals.

```markdown
# Post-Mortem: <Incident title>

**Date of incident:** <date>  **Severity:** SEV-1 | SEV-2 | SEV-3
**Author:** <name>  **Status:** Draft | Review | Final
**Time to detect:** <duration>  **Time to resolve:** <duration>

## Summary
<3-4 sentences: what happened, who was affected, and the impact>

## Timeline
| Time (UTC) | Event |
|---|---|
| HH:MM | <what happened> |

## Root cause
<The deepest "why" - use the 5 Whys technique to go beyond symptoms>

## Contributing factors
<Other conditions that made the incident possible or worse>

## What went well
<Things that worked during response - detection, communication, tooling>

## What went poorly
<Process or system gaps exposed by the incident>

From mkurman/zorai, MIT.

More from mkurman/zorai