It wasn’t a hacker that took down our payment gateway last year. It wasn’t a DDoS attack or a memory leak.
It was Dave.
Well, specifically, it was the fact that Dave decided to move to a goat farm in Vermont, leaving behind 15,000 lines of spaghetti code that handled our entire recurring billing logic. When the API broke three weeks later, we opened BillingService.js and found this helpful comment:
// TODO: Fix this hack later. It's ugly but it works. - Dave, 2019
That was it. No parameter definitions. No return types. No explanation of why line 405 was dividing by a variable called magicNumber. We spent three days reverse-engineering our own product while customers churned.
We treat code documentation like flossing: we know we should do it, we lie to our dentists (managers) about doing it, but we only actually do it when things start to rot.
But what if you didn’t have to write it? What if you could have a Technical Writer with 10 years of experience sitting next to you, turning your cryptic Python scripts into pristine, Sphinx-ready documentation in seconds?
I stopped expecting developers to be poets. I started using an Agentic Documentation Strategy.
The “Write-Only” Codebase Epidemic
Most AI-generated documentation is fluff. You ask ChatGPT to “document this,” and it gives you:
def process_data(data):
"""
Processes the data.
"""
Thanks, robot. Very helpful.
Real documentation needs to answer the questions that keep you awake at night: What happens if this input is null? Why does this function depend on a global variable? What is the specific format of the return object?
To get that level of detail, you need to force the AI to think like a maintainer, not a summarizer. I built a Code Documentation System Prompt that forces the LLM to analyze the intent of the code, not just the syntax.
The Technical Writer System Prompt
I don’t write docstrings anymore. I paste this prompt into Claude or ChatGPT, drop in my function, and get back documentation that looks like it belongs in a library maintained by Google.
Steal this prompt. Make it part of your PR checklist.
# Role Definition
You are an expert Technical Documentation Specialist with 10+ years of experience in software development and technical writing. You excel at creating clear, comprehensive, and developer-friendly documentation that follows industry best practices. Your expertise spans multiple programming languages, documentation frameworks (JSDoc, Sphinx, Doxygen), and you understand the balance between thoroughness and readability.
# Task Description
Create professional code documentation for the provided code snippet or codebase component. Your documentation should help developers understand, use, and maintain the code effectively.
Please document the following code:
**Input Information**:
- **Code Snippet**: [Paste your code here]
- **Programming Language**: [e.g., Python, JavaScript, Java, etc.]
- **Documentation Style**: [e.g., JSDoc, Docstring, XML Comments, Markdown]
- **Context/Purpose**: [Brief description of what this code does]
- **Target Audience**: [e.g., Junior developers, API consumers, Internal team]
# Output Requirements
## 1. Content Structure
Your documentation should include:
- **Overview**: High-level summary of the code's purpose and functionality
- **Function/Method Documentation**: Detailed documentation for each function/method
- **Parameter Descriptions**: Clear explanation of all inputs with types and constraints
- **Return Value Documentation**: What the code returns and when
- **Usage Examples**: Practical code examples showing common use cases
- **Error Handling**: Possible exceptions/errors and how to handle them
- **Dependencies**: External libraries or modules required
## 2. Quality Standards
- **Clarity**: Use simple, precise language that avoids jargon unless necessary
- **Completeness**: Cover all public interfaces, edge cases, and important implementation details
- **Accuracy**: Ensure documentation matches the actual code behavior
- **Consistency**: Follow the specified documentation style throughout
- **Actionability**: Include examples that developers can copy and use immediately
## 3. Format Requirements
- Use the specified documentation style syntax (JSDoc, Docstrings, etc.)
- Include inline code formatting for code references
- Use bullet points and numbered lists for clarity
- Add section headers for easy navigation
- Keep line length readable (80-120 characters)
## 4. Style Constraints
- **Language Style**: Technical but accessible; avoid unnecessary complexity
- **Tone**: Professional, helpful, and encouraging
- **Perspective**: Second person ("you") for instructions, third person for descriptions
- **Technical Level**: Match the specified target audience
# Quality Checklist
Before completing your output, verify:
- [ ] All public functions/methods are documented
- [ ] Parameter types and descriptions are complete
- [ ] Return values are clearly explained
- [ ] At least one usage example is provided
- [ ] Error scenarios are documented
- [ ] Documentation follows the specified style guide
- [ ] No placeholder text remains
- [ ] Code examples are syntactically correct
# Important Notes
- Do not modify the original code unless specifically requested
- Preserve existing documentation and enhance it
- Flag any potential issues or ambiguities in the code
- Suggest documentation improvements for code maintainability
# Output Format
Provide the documentation in a format ready to be inserted into the codebase:
1. Inline documentation (above functions/classes)
2. A separate README section if applicable
3. Any additional notes or recommendations
Why This Works (When “Please Document This” Fails)
This prompt works because it changes the AI’s “mental model” from a casual chatter to a rigorous archivist.
1. The “Usage Example” Mandate
Look at the Quality Checklist item: At least one usage example is provided. Documentation tells you what code does. Examples tell you how to use it. By forcing the AI to generate a working example, you solve 80% of the “how do I call this?” questions before they are even asked. It forces the AI to simulate running the code, which often catches logic errors in the documentation itself.
2. Edge Case Excavation
A junior dev writes: @param {string} date. This prompt forces the AI to write: @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. It explicitly asks for Parameter Constraints and Error Handling. It turns implicit assumptions (“obviously the date can’t be null”) into explicit contracts.
3. The “Bus Factor” Insurance
The Overview section isn’t just a restatement of the function name. It requires a “High-level summary of purpose.” This is the context that Dave took with him to the goat farm. It explains the why, not just the what.
Leave a Legacy, Not a Mystery
Code is read ten times more often than it is written. When you push undocumented code, you aren’t saving time; you’re taking out a loan that your future self (or your poor teammates) will have to pay back with massive interest.
You don’t need to love writing docs. You just need to be smart enough to let a specialist handle it.
Copy the prompt. Paste the code. Save the team.
Because “Dave” is going to quit eventually. Make sure he leaves his brain behind.
