Repository documentation
AI Repository Documentation: Keep Guides Tied to Code
Repository documentation is useful when a reader can follow it against the current code. AI-generated prose can sound complete while containing nonexistent commands or outdated assumptions. Build the documentation from inspected sources and verify the operational steps.
Identify the source of truth for each section
Use package scripts for commands, configuration files for supported options, CI workflows for automated checks, and application code for behavior. Record the repository revision used to prepare the documentation.
Distinguish what the code establishes from what requires an owner’s decision. Support commitments, service-level objectives, production access procedures, and billing policies should not be inferred from a directory name.
- Inspect existing documentation before replacing it.
- Identify the intended reader and their prerequisites.
- Use actual file paths and script names.
- Flag missing operational information rather than inventing it.
Write a setup guide that can be followed
List required tools, supported versions, installation steps, configuration, and the command that starts the application. Explain where commands run when the repository contains multiple packages or services.
Document environment-variable names and safe example values, never real credentials. State how a developer obtains required access without copying secret material into the guide.
Separate explanations from operational runbooks
Architecture documentation explains responsibilities and data flow. A runbook explains what to check, what action is authorized, how success is verified, and when to escalate. Mixing these purposes makes urgent instructions harder to find.
For actions that can delete data, change production state, or expose credentials, include the required authorization and recovery considerations. Do not turn an untested suggestion into a confident operational command.
- Name the symptom or task the runbook addresses.
- Explain expected results and failure conditions.
- Identify escalation ownership when known.
- Describe rollback only when the underlying procedure is established.
Verify instructions and give the document an owner
Run safe setup and verification steps in an appropriate environment. Check links, file paths, configuration names, and examples against the repository. Clearly label procedures that could not be exercised.
Finish with a focused documentation diff and a list of unresolved questions. Keep related documentation updates in the same review as future code changes; generation alone does not keep a document synchronized.