$
copilot --idea "Documentation Machine"
→
Generate comprehensive, accurate docs from your code — READMEs, API docs, runbooks, and decision logs
The Problem
Documentation is always the last thing that gets done and the first thing that goes stale. Engineers would rather write code than docs. The README was last updated when the project had 3 files.
What You'll Build
A documentation generation workflow that produces:
- A comprehensive README with setup guide and architecture overview
- API documentation with request/response examples
- Inline code documentation (JSDoc, docstrings, etc.)
- An operational runbook for on-call engineers
- A decision log explaining architectural choices
Step-by-Step Walkthrough
Phase 1: README Generation
$
"Generate a README.md for this project that includes:
- Project name and one-line description
- Architecture diagram (Mermaid)
- Prerequisites and setup instructions
- How to run locally, run tests, and deploy
- Environment variables with descriptions
- Contributing guidelines
Test every command in the setup instructions to make sure they work."
Phase 2: API Documentation
$
"Generate API documentation for every endpoint in this application.
For each endpoint include:
- HTTP method and path
- Description of what it does
- Request headers, query params, and body schema
- Example request with curl
- Success response with example JSON
- Error responses (400, 401, 404, 500) with examples
Output as OpenAPI 3.0 YAML."
Phase 3: Code Documentation
$
"Add JSDoc comments to every exported function in src/.
Include @param, @returns, @throws, and @example.
The @example should be a realistic, copy-pasteable code snippet.
Don't document obvious getters/setters — focus on business logic."
Phase 4: Operational Runbook
$
"Create a runbook for on-call engineers covering:
1. How to check if the service is healthy
2. Common error messages and what they mean
3. How to restart the service safely
4. How to roll back to the previous version
5. Database troubleshooting (connection issues, slow queries)
6. Escalation contacts and procedures
Include actual commands, not placeholder text."
Phase 5: Decision Log
$
"Analyse the codebase and create an Architecture Decision Record (ADR) log.
Infer decisions from the code:
- Why this database? (look at the ORM and schema)
- Why this framework? (look at middleware and patterns)
- Why this auth approach? (look at the auth implementation)
For each decision, document: Context, Decision, Consequences."
Pro Tips
• Copilot reads the actual code — its docs are more accurate than human-written docs that went stale
• Run the setup instructions on a fresh machine to verify they work
• Use the explore agent to scan the whole codebase before generating docs
• Set a recurring reminder to regenerate docs monthly
What You'll Learn
• Technical writing patterns for different audiences
• OpenAPI/Swagger specification
• Architecture Decision Records (ADRs)
• Operational documentation best practices