How to Write Code Documentation with AI

Documentation helps people understand how to use, change and operate software. AI coding assistants can propose inline comments, docstrings, examples and README text from the source code and repository context. GitHub documents that Copilot can suggest comments based on code; like any generated suggestion, it may be accepted, modified or rejected. The model can describe what code appears to do, but it cannot reliably infer every design reason, operational constraint or undocumented dependency. Start with the reader’s task. An API doc needs inputs, outputs, side effects, errors and a minimal working example. A README may need installation, configuration, common commands and troubleshooting. A comment should explain a non-obvious invariant or reason, not repeat the next line in English. Provide relevant files and project conventions, but avoid sending secrets, private customer data or code to an unapproved service. Review every factual statement against the implementation and tests. Run commands in a clean environment, compile examples, verify names and types, and confirm that environment variables and paths exist. Be especially cautious with concurrency behavior, security guarantees, performance claims and edge cases: a plausible explanation is not evidence. Ask the assistant to identify uncertainty and cite the source file or test that supports a claim, then inspect it yourself. Documentation is part of the change. Update it when behavior, flags, API contracts or setup steps change; include the docs in code review and assign ownership for operational pages. Keep examples small and executable. If the implementation is unclear, improve the code or tests before writing prose around an assumption. AI can reduce blank-page effort, while developers remain responsible for correctness, clarity and maintenance.