Documentation templates for software teams, organised by what you build and how you work.
Example. A backend team adopting Kanban starts in
general-swe/kanban/, reads the group README to see which documents earn their place, and copies the ones that do into their own repository.
| What it is | Templates and READMEs, not a framework or a tool. Copy what you need. |
| Start here | general-swe/foundations/ — the documents most teams need before anything else |
| Who it's for | Engineers writing a design doc or runbook, tech leads setting up documentation practice, anyone new to a methodology's paperwork |
| Status | Growing. See Coverage below for what is finished. |
Every template tells you what goes in each section and how to write it. Every group of templates comes with a README that answers three questions: when to use each document, why it helps, and where it should live.
- Pick your area. Backend service, web app, game, data pipeline, platform. Areas differ in what they must document: a game studio needs an art bible, a payments team needs a threat model.
- Pick your methodology. Scrum, Kanban, plan-driven, Lean, Shape Up, or none of them. If none, start in the area's
foundations/group, which is methodology-agnostic. - Read the group README first. It says which documents in that group earn their place and which to skip. Skipping is a valid answer and the READMEs say so.
- Copy the template into your own repository or wiki. Delete the guidance text as you fill each section.
You do not need to adopt a methodology wholesale to use its templates. Take the retrospective format without taking sprints.
<area>/ what you build
<methodology>/ how you work
README.md when, why, and where each document lives
<document>.md the template itself
| Area | What it covers |
|---|---|
general-swe/ |
Documents any software team needs, whatever the domain: architecture decisions, design docs, runbooks, postmortems, review standards. |
web-development/ |
Browser and API-facing work: frontend architecture, API contracts, accessibility, performance budgets, rollout plans. |
game-development/ |
Games and interactive media: design documents, art and audio direction, level design, playtesting, milestone delivery, certification. |
data-engineering/ |
Pipelines, warehouses, and models: data contracts, metric definitions, dataset and model documentation, quality specifications. |
platform-engineering/ |
Infrastructure and operations: service level objectives, on-call practice, disaster recovery, capacity planning, change management. |
ai-assisted-development/ |
Working with coding agents and language models: agent instruction files, task plans, task specifications, evaluation plans. |
Within each area, foundations/ holds documents that do not depend on a methodology. The other folders are named for the methodology they serve.
Every group README answers this per document, because getting it wrong is the most common reason documentation rots. Two questions decide it:
Does the document become wrong when the code changes? If yes, it belongs in the repository next to the code, so one commit changes both and code review catches the drift. Architecture decision records and API contracts fail this way.
Is the value in the discussion or the final text? If it's in the discussion, the document needs threaded comments and access for people who don't use pull requests. Design docs under review belong in a wiki. Extract the durable outcome into the repository afterward.
Some documents belong in neither. Sprint backlogs belong in the tracker that already holds them. Kanban policies belong on the board, read at the moment a decision is made. Regulated records requiring signatures belong in a controlled document system.
- Not a methodology guide. The READMEs explain enough of Scrum or Kanban to make the documents make sense, then point at the primary sources.
- Not a standard. Nothing here is normative. Where credible sources disagree, the READMEs say so instead of picking a side quietly.
- Not a checklist to complete. Documents you don't need cost time to write and time to distrust. Every group README names the documents you can safely skip.
Documentation supports development. When a document stops helping the team build software, delete it.
Contributions are welcome. The bar is high on purpose: a resource about writing well has to be written well.
Raise an issue before opening a pull request, research before you write, and keep each pull request to one change. CONTRIBUTING.md has the full detail — the research discipline, what a template and a group README must contain, and the writing principles every committed word follows.
This repository grows a group at a time. A folder appears once its README and templates are researched and written, not before. Check the folder listing above for current coverage.
general-swe/README.md— documents any team needs regardless of domain; start here if you're unsure where else to lookweb-development/README.md— browser and API-facing workgame-development/README.md— games and interactive mediadata-engineering/README.md— pipelines, warehouses, and modelsplatform-engineering/README.md— infrastructure and operationsai-assisted-development/README.md— working with coding agents and language models