Technical Documentation · Reference
A document exists to get intent across a boundary its author will not be present at. This is the map of those boundaries: the nine gates a bid has to pass, the six stages delivery moves through, and the document each one owes — who writes it, who signs it, and what it is for.
Bid & Proposal — 9 gates: Qualify 4, RFP 4, Solution 5, Pricing 4, Proposal 6, Deal Review 3, Submit 2, Orals 3, Award 4. 3.9 documents per gate. Delivery — 6 stages: Discovery 6, Planning 9, Architecture 9, Development 9, Review 8, Handover 8. 8.2 documents per stage.
Two Clocks
The two lifecycles on this page are cut at different granularities on purpose. Counting one against the other is counting doors against rooms.
A bid moves in gates. Each one is a moment: a decision somebody signs, on a date, and four of the nine dates belong to the customer rather than to you. There are nine because a competitive bid commits to an outside party nine separate times. Delivery moves in stages. Each one is an interval of work with real width, and four of the six reopen on every increment — so the track is a loop drawn flat, not a queue. Nine gates is not more work than six stages; it is a finer ruler laid against a shorter, harder-edged thing.
The bid track has 9 gates, each a decision on a date: Opportunity Qualification & Capture Planning — Bid / no-bid, signed by Capture lead + sales leadership; RFP Analysis & Clarification — Clarification questions submitted, signed by Bid manager; Solution Development — Solution locked, signed by Solution architect + delivery lead; Cost Estimation & Pricing — Cost baseline signed off, signed by Finance + commercial; Proposal Development — Draft complete, Red Team ready, signed by Proposal manager; Deal Review & Approval — The company stands behind the offer, signed by Deal desk / executive sponsor; Production & Submission — Submitted, on time and compliant, signed by Bid manager; Orals, Clarifications & Negotiation — Best and final offer agreed, signed by Commercial lead; Award, Debrief & Transition — Award decided, handover accepted, signed by Customer, then capture + delivery leads. The delivery track has 6 stages, each an interval of work: Discovery & Ideation — Ends once the problem is agreed; Planning — Reopens every increment; Architecture & Design — Reopens when a decision is reversed; Development — Runs continuously; Review & Launch — Repeats every release; Handover & Maintenance — Never ends — only changes hands. Gates average 3.9 documents each; stages average 8.2.
3.9 documents per gate — 35 across the track.
8.2 documents per stage — 49 across the track.
Framework
Is the reader acting or thinking? Are they studying or working? Every documentation failure on this page starts with getting that pair wrong.
The Diataxis map places tutorials at practical steps during study, how-to guides at practical steps during work, explanation at theoretical knowledge during study, and reference at theoretical knowledge during work.
e.g. A 'Getting started' guide that walks you through deploying your first service.
✗ A tutorial that explains too much theory before letting the reader do anything.
e.g. How to rotate API keys without downtime.
✗ A how-to that stops to explain why the technology works the way it does.
e.g. An API endpoint reference listing all parameters, types, and error codes.
✗ Reference docs that include tutorials or opinions — mix contamination is the most common Diataxis mistake.
e.g. An ADR explaining why the team chose event sourcing over a traditional CRUD model.
✗ Explanation docs that drift into instructions — they should answer 'why' not 'how'.
Dependency Graph · Document Relationships
Hover or tab to any node to trace its prerequisite chain across both the bid and delivery tracks. Click or press Enter to open the full document detail.
Framework Matrix
Every document type placed on both axes at once. The empty cells are the finding: almost nothing in an engineering lifecycle is a tutorial.
Tutorial
Learning-oriented
How-To Guide
Task-oriented
Reference
Information-oriented
Explanation
Understanding-oriented
KEYSClick any chip to open that document's full detail panel.
Discovery & Ideation: Tutorial 0, How-To Guide 0, Reference 4, Explanation 2. Planning: Tutorial 0, How-To Guide 0, Reference 8, Explanation 1. Architecture & Design: Tutorial 0, How-To Guide 0, Reference 8, Explanation 1. Development: Tutorial 0, How-To Guide 3, Reference 6, Explanation 0. Review & Launch: Tutorial 0, How-To Guide 4, Reference 4, Explanation 0. Handover & Maintenance: Tutorial 0, How-To Guide 2, Reference 5, Explanation 1
Documentation Maturity · Self-Assessment
Five levels from chaotic to continuous. Find your current state before you plan the next step — every level's advice assumes you are standing on the one below it.
Characteristics
You are here if…
To reach Level 2
Typical org pattern
Pre-Sales Track · 9 Gates
Nine gates, because a competitive bid commits to the customer nine separate times. Each one ends in a decision somebody signs, and four of the dates belong to the customer, not to you.
Everything below the bridge assumes a contract already exists. It doesn't — not yet. The RFP and bid lifecycle is a separate track with its own owners (capture and bid management, not delivery), its own gate reviews (bid/no-bid and deal desk, not design review), and a hard external deadline. It runs from qualifying the opportunity through award, debrief and a structured handover — which is exactly where it connects into Delivery Stage 01: Discovery & Ideation.
Decide whether to bid, and start winning before writing anything
Shred the RFP into requirements and use the Q&A window before it closes
Design the offering: technical solution, delivery model, staffing, win themes
Build the cost bottom-up, set the price top-down, and know the difference
Write for the evaluator: compliant, scorable, and easy to mark
Internal governance decides whether the company stands behind this offer
Compliance is binary — perfect and on time, or rejected
The bid isn't over at submission — now you defend it in person
Win or lose, extract the value: lessons, content, and a clean handover
Gate 1 Opportunity Qualification & Capture Planning: Decide whether to bid, and start winning before writing anything. Ends when Bid / no-bid, signed by Capture lead + sales leadership. Gate 2 RFP Analysis & Clarification: Shred the RFP into requirements and use the Q&A window before it closes. Ends when Clarification questions submitted, signed by Bid manager, on the customer's date. Gate 3 Solution Development: Design the offering: technical solution, delivery model, staffing, win themes. Ends when Solution locked, signed by Solution architect + delivery lead. Gate 4 Cost Estimation & Pricing: Build the cost bottom-up, set the price top-down, and know the difference. Ends when Cost baseline signed off, signed by Finance + commercial. Gate 5 Proposal Development: Write for the evaluator: compliant, scorable, and easy to mark. Ends when Draft complete, Red Team ready, signed by Proposal manager. Gate 6 Deal Review & Approval: Internal governance decides whether the company stands behind this offer. Ends when The company stands behind the offer, signed by Deal desk / executive sponsor. Gate 7 Production & Submission: Compliance is binary — perfect and on time, or rejected. Ends when Submitted, on time and compliant, signed by Bid manager, on the customer's date. Gate 8 Orals, Clarifications & Negotiation: The bid isn't over at submission — now you defend it in person. Ends when Best and final offer agreed, signed by Commercial lead, on the customer's date. Gate 9 Award, Debrief & Transition: Win or lose, extract the value: lessons, content, and a clean handover. Ends when Award decided, handover accepted, signed by Customer, then capture + delivery leads, on the customer's date.
Color-team review glossary
Reviews capture strategy and win themes before solutioning begins.
Reviews storyboards and the annotated outline before full writing starts.
Scores the complete draft exactly as the customer's evaluators would.
Reviews cost, price, and commercial risk before it's locked in.
Final executive review of the submission-ready package.
Independent fresh-eyes review of the submission package for readability, clarity, and compliance comprehension by someone with no prior involvement in writing it.
Gate 01 · 4 documents
Decide whether to bid, and start winning before writing anything
ENDS WHEN · Bid / no-bid · signed by Capture lead + sales leadership
Gate 02 · 4 documents
Shred the RFP into requirements and use the Q&A window before it closes
ENDS WHEN · Clarification questions submitted · signed by Bid manager · the customer's date
Gate 03 · 5 documents
Design the offering: technical solution, delivery model, staffing, win themes
ENDS WHEN · Solution locked · signed by Solution architect + delivery lead
Gate 04 · 4 documents
Build the cost bottom-up, set the price top-down, and know the difference
ENDS WHEN · Cost baseline signed off · signed by Finance + commercial
Gate 05 · 6 documents
Write for the evaluator: compliant, scorable, and easy to mark
ENDS WHEN · Draft complete, Red Team ready · signed by Proposal manager
Gate 06 · 3 documents
Internal governance decides whether the company stands behind this offer
ENDS WHEN · The company stands behind the offer · signed by Deal desk / executive sponsor
Gate 07 · 2 documents
Compliance is binary — perfect and on time, or rejected
ENDS WHEN · Submitted, on time and compliant · signed by Bid manager · the customer's date
Gate 08 · 3 documents
The bid isn't over at submission — now you defend it in person
ENDS WHEN · Best and final offer agreed · signed by Commercial lead · the customer's date
Gate 09 · 4 documents
Win or lose, extract the value: lessons, content, and a clean handover
ENDS WHEN · Award decided, handover accepted · signed by Customer, then capture + delivery leads · the customer's date
Across All Nine Gates
Compliant is the entry ticket. These eight cut across all nine gates, and are the difference between a proposal that scores and one that wins.
The cheapest bid to lose is the one you never start. But once past bid/no-bid, resource it to win — half-hearted bids cost almost as much as serious ones and win nothing.
A non-compliant proposal is rejected unread; a merely compliant one loses to a responsive one. Compliance matrix first, win themes second — but always both.
Evaluators score dozens of documents against a rubric under time pressure. Mirror the RFP structure, answer first and elaborate second, make every scoring criterion findable in seconds.
Every claim — "proven", "experienced", "innovative" — that isn't attached to a metric, a named project, or a verifiable artefact is filler that dilutes the claims that do have proof.
Bottom-up cost and top-down price-to-win are built independently. The gap between them is closed by explicit decisions — descope, redesign, margin — never by quietly shrinking estimates.
Pink, Red, and Gold teams need independent reviewers, the customer's real criteria, and enough calendar left to act on findings. A review that can't change the outcome is a ceremony.
Proposal text, clarification answers, orals claims, negotiation concessions — assume all of it is binding, and review it at that standard.
A win handed over as a document dump becomes delivery's problem and next year's reference-client risk. The handover pack is part of the bid, not an afterthought.
Where the bid becomes the project
Award, Debrief & Transition
Discovery & Ideation
The Sales-to-Delivery Handover Pack carries the solution, assumptions, risk register and budget straight into the Opportunity Brief — the bid team's knowledge becomes the delivery team's starting point.
Stage 01 · 6 documents
Capture the problem before building the solution
RHYTHM · Ends once the problem is agreed
Stage 02 · 9 documents
Agree on scope, requirements, and risk before a line of code
REPEATS · Reopens every increment
Stage 03 · 9 documents
Record the decisions that shape everything downstream
REPEATS · Reopens when a decision is reversed
Stage 04 · 9 documents
Keep the team aligned while the system is being built
REPEATS · Runs continuously
Stage 05 · 8 documents
Prepare operators and users for what you're shipping
REPEATS · Repeats every release
Stage 06 · 8 documents
Preserve knowledge beyond the original team
RHYTHM · Never ends — only changes hands
Communication Matrix
Click a role to keep only the documents it owns or contributes to. Hover a row to trace it across every column.
Documentation load by role — share of all 49 documents
| Document | Engineering | PM | Design | QA | Ops/SRE | Leadership | Legal/Compliance | End Users |
|---|---|---|---|---|---|---|---|---|
| Stage 1 — Discovery & Ideation | ||||||||
| Opportunity Brief | ||||||||
| Research Notes | ||||||||
| Assumption Log | ||||||||
| Competitive Analysis | ||||||||
| Stakeholder Map | ||||||||
| Value Proposition | ||||||||
| Stage 2 — Planning | ||||||||
| PRD | ||||||||
| FSD | ||||||||
| NFR Doc | ||||||||
| WBS | ||||||||
| Risk Register | ||||||||
| Definition of Done | ||||||||
| Dependency Map | ||||||||
| Capacity Plan | ||||||||
| Communication Plan | ||||||||
| Stage 3 — Architecture & Design | ||||||||
| ADR | ||||||||
| Tech Design Doc | ||||||||
| System Design | ||||||||
| API Contract | ||||||||
| Data Model | ||||||||
| DPIA | ||||||||
| Sequence Diagrams | ||||||||
| IaC Docs | ||||||||
| SLO Definition | ||||||||
| Stage 4 — Development | ||||||||
| README | ||||||||
| Inline Docs | ||||||||
| Changelog | ||||||||
| Dev Setup Guide | ||||||||
| Test Plan | ||||||||
| PR Template | ||||||||
| Coding Standards | ||||||||
| Migration Guide | ||||||||
| Feature Flag Docs | ||||||||
| Stage 5 — Review & Launch | ||||||||
| Release Notes | ||||||||
| Runbook | ||||||||
| Incident Playbook | ||||||||
| Security Review | ||||||||
| Load Test Report | ||||||||
| A11y Audit | ||||||||
| Launch Checklist | ||||||||
| Help Center Docs | ||||||||
| Stage 6 — Handover & Maintenance | ||||||||
| Handover Doc | ||||||||
| Post-Mortem | ||||||||
| Knowledge Base | ||||||||
| Deprecation Notice | ||||||||
| DR Plan | ||||||||
| On-Call Guide | ||||||||
| Tech Debt Register | ||||||||
| Arch Fitness | ||||||||
Responsibility matrix for 49 document types across 8 roles. Primary owners by role: Engineering 28, PM 14, Design 2, QA 8, Ops/SRE 8, Leadership 3, Legal/Compliance 4, End Users 2.
Best Practices · 12 pairs
Opinionated rules for documentation that actually gets read, used and maintained. Each pair is one decision, shown both ways.
Docs as Code · Principles
Apply the rigour you already apply to code: version it, lint it, test it, and generate it wherever the source already knows the answer.
Store docs alongside code in Git. PRs, reviews, and blame work for docs too — the same discipline that keeps code honest keeps docs honest.
Git + GitHub/GitLabEnforce style, tone, and structure automatically. Catch passive voice, unclear headings, and broken links before review reaches human eyes.
Vale, markdownlintAdd last-modified timestamps to frontmatter. CI alerts when a doc hasn't been reviewed in 90 days. Stale is a bug.
GitHub ActionsAPI docs from OpenAPI specs, type docs from TypeScript, architecture maps from code analysis. Auto-generated docs can't go stale.
Redoc, TypeDocLink checking, example validation, and screenshot testing for UI docs. If you wouldn't ship untested code, don't ship untested docs.
htmlproofer, PlaywrightDocs in the repo stay in sync with code; external wikis drift. The tradeoff is discoverability vs. co-location — choose deliberately.
Docusaurus, MintlifyOf 5 criteria, docs in the repo win on Sync with code and Versioning per release; an external wiki wins on Discoverability for non-engineers, Granular access control, Non-technical contributor access.
Tool Ecosystem · Curated Reference
Writing, diagramming, API docs, linting and automation — each entry says what it is best at and which document type it pairs with.
All-in-one workspace with rich blocks and database views.
Git-backed docs with automatic versioning and branching.
React-based static site generator with versioning built in.
Beautiful API docs and developer portals with zero configuration.
CLI and static-site generators for creating, numbering, and publishing MADR-format Architecture Decision Records.
Docs-like-code plugin for Spotify's Backstage developer portal — renders each service's Markdown docs alongside its catalog entry.
Diagrams as code embedded in Markdown — no design tool needed.
Whiteboard-style sketching with a hand-drawn aesthetic.
Declarative diagramming language with layout auto-computation.
Text-based UML generation from plain-text DSL.
Industry-standard specification for REST APIs with broad tooling support.
Beautiful, three-panel OpenAPI renderer with zero configuration.
API design, mocking, and documentation platform for API-first teams.
Generates browsable API reference documentation directly from TypeScript source and doc comments.
Prose linter with custom style rules, tone checks, and readability scores.
Markdown structure and style linter with extensive rule configuration.
Catches insensitive, inconsiderate writing in your documentation.
CI/CD pipelines for docs: lint, link-check, freshness audit, and deploy.
Automatically updates documentation tooling dependencies.
Deploy previews for documentation sites on every pull request.
Lifecycle Governance · States & Cadences
Govern the full arc from first draft to archival. Freshness is a design requirement, not an afterthought.
Author
Creates document from template; fills in context, decisions, and open questions.
Author → Reviewers
Author requests review; reviewers comment on accuracy, completeness, and clarity.
Reviewer / Approver
Reviewer approves; document is merged or published to canonical location.
Automated CI / Owner
90 days without update triggers automated alert; owner decides to update or archive.
Owner
Owner marks as superseded or retired; document preserved as historical record.
Draft (Author): Creates document from template; fills in context, decisions, and open questions. In Review (Author → Reviewers): Author requests review; reviewers comment on accuracy, completeness, and clarity. Published (Reviewer / Approver): Reviewer approves; document is merged or published to canonical location. Stale (Automated CI / Owner): 90 days without update triggers automated alert; owner decides to update or archive. Archived (Owner): Owner marks as superseded or retired; document preserved as historical record.
Continuous
CI re-checks it
Event-driven
Something happened
Release-paced
Moves with the ship cycle
Calendar-paced
A date, not an event
Never
Superseded, not revised
Continuous: Architecture Fitness (Continuous / CI; review now if Fitness function fails in pipeline). Event-driven: Runbook (After every incident; review now if Any production incident touching the system); PRD (When requirements change; review now if Stakeholder scope change or user research invalidates assumptions); API Contract (Before every breaking change; review now if Any change to request/response schema or auth); Handover Doc (30 days before transition; review now if Team member departure confirmed). Release-paced: Risk Register (Every major milestone; review now if New risk identified or risk materialises); Security Review (Every major release; review now if New data type handled or threat landscape shift). Calendar-paced: SLO Definition (Quarterly; review now if SLO breach or business model change); Knowledge Base (Every 6 months; review now if Product feature change renders article inaccurate). Never: ADR (Never — supersede instead; review now if When the decision is reversed or revisited)
AI-Specific Considerations
Three places where an AI system loses context faster than a conventional one — and the document that holds it.
AI systems accumulate invisible decisions — which model version, which prompt strategy, which embedding dimensionality. ADRs make these auditable. When a model update breaks production behaviour, you need to know what was decided and why, not just what changed.
Model drift is not a bug — it is a property of production ML systems. Your runbook should include drift detection thresholds, retraining triggers, and rollback procedures. An on-call engineer should be able to execute the full response at 3am without Slack.
When AI capabilities are embedded in a product and the team that built them moves on, what gets lost is not the code — it is the intent. Which prompts are load-bearing? Which system messages cannot change without breaking downstream behaviour? Document it before you leave.