I've noticed that most of the disappointment technical writers report with AI-generated drafts traces back to the prompt, not the model. AI tools are only as good as the instructions you give them, and a lot of us — myself included, early on — were writing prompts like Google searches: a few keywords and a hope for the best.
The mental shift that actually helped me was treating a prompt less like a search query and more like a briefing you'd give a smart new hire who's never met your audience. The difference is precision — how much of the context in your head you actually bothered to write down.
| Generic Prompt | Engineered Prompt |
|---|---|
| "Write API documentation" | "Write API documentation for a REST endpoint that accepts POST requests with JSON payload containing email and password. Include: endpoint path, HTTP method, authentication requirement (Bearer token), request body example with actual field names (email, password), response codes (200 success, 401 unauthorized, 422 validation error), and Python example using requests library" |
| "Explain what REST is" | "Explain REST principles specifically for a developer who knows SQL but has never built an API. Use a database analogy. Include 3 real-world examples of how GET, POST, and DELETE map to actual database operations" |
| "Create code examples" | "Create 5 code examples in Python showing how to handle pagination in API responses. Start with a naive implementation that breaks, then show the correct solution. Include error handling for network timeouts" |
What I've Found Actually Makes a Prompt Work
Three things tend to do most of the work: telling the model who's reading the output, telling it exactly what shape the output should take, and showing it — not just describing — the style you want.
1. CONTEXT: Who's reading this?
Good: "For senior backend engineers" Better: "For backend engineers with 3+ years experience using Python and PostgreSQL but no experience with caching"
2. CONSTRAINT: What's the specific output?
Good: "Write code examples" Better: "Write 3 code examples showing caching strategies: in-memory, Redis, and database query caching. Each should handle cache invalidation. No comments, just clean code with variable names that explain intent"
3. EXAMPLE: Show what you want
Good: "Follow this style" Better: "Follow this exact style:
# BAD
def fetch_data(user_id):
return database.get_user(user_id)
# GOOD
def get_user_by_id(user_id: int) -> User:
cached_user = cache.get(f'user:{user_id}')
if cached_user:
return cached_user
user = database.query_user_by_id(user_id)
cache.set(f'user:{user_id}', user, ttl=3600)
return user"
Real-World Prompt Templates
Template 1: Generate API Documentation
I'm documenting a [TYPE: REST/GraphQL/gRPC] API endpoint.
CONTEXT: - Audience: [experience level of developers] - Use case: [what the endpoint does] - Authentication: [how it's secured]
ENDPOINT DETAILS: - Method: [HTTP method] - Path: [/api/path] - Purpose: [what it accomplishes]
REQUIRED IN OUTPUT: 1. Endpoint description (2 sentences max) 2. Authentication requirement 3. Request body with all fields and types 4. Response examples for: success (200), validation error (422), auth error (401) 5. Code example in [LANGUAGE] 6. Common mistakes (2-3 pitfalls) 7. Rate limiting info
STYLE: [Technical but conversational, assume reader knows basic API concepts]
Template 2: Generate Code Examples
CONTEXT: - Language: [Python/JavaScript/Go] - Audience: [Beginner/Intermediate/Advanced] - They know: [e.g., "basic Python, SQL, but no async/await experience"]
TASK: - Show [specific code pattern] - Include [specific functionality]
REQUIREMENTS: 1. Start with a simple, working example 2. Identify 2 problems with the naive implementation 3. Show refactored version addressing those problems 4. Include error handling for [specific errors] 5. Add a 1-line comment only where logic isn't obvious
OUTPUT FORMAT: # [Pattern Name] [Brief explanation]
[Naive implementation]
Problems: 1. [Problem 1] 2. [Problem 2]
[Improved implementation]
Template 3: Generate Technical Explanations
CONTEXT: - Concept: [e.g., "Database indexing"] - Audience knows: [e.g., "What a database is, what SELECT queries are"] - Audience doesn't know: [e.g., "Why indexes matter, how they work internally"]
TASK: Explain [concept] using [analogy/metaphor]
STRUCTURE: 1. What it is (1 paragraph) 2. Why it matters (with numbers/metrics if possible) 3. How it works (step by step) 4. Real example from [specific domain] 5. When NOT to use it 6. Key takeaway (1 sentence)
TONE: Technical but accessible, conversational, avoid marketing speak
Common Mistakes and How to Fix Them
| Mistake | Example | Fix |
|---|---|---|
| Vague audience | "For developers" | "For frontend developers with React experience transitioning to backend" |
| No length guidance | "Write documentation" | "Write 500-800 word documentation covering installation, basic usage, and troubleshooting" |
| Unclear format | "Create examples" | "Create 4 examples: setup, basic auth, error handling, advanced usage. Each ~30 lines, Python only" |
| No context about what exists | "Summarize this" | "Summarize this 50-page design document into 1 page for engineers who haven't read it, assuming they know our tech stack" |
| Missing constraints | "Make it better" | "Improve this for clarity, remove jargon, keep it under 200 words, add one concrete example" |
How I Sanity-Check a Prompt
Before accepting AI output, I run through a few honest questions:
- Does it match the level of detail you specified? If your constraint was "2-sentence explanation" and AI gave you 10 paragraphs, your prompt was too open-ended.
- Is the tone right? If you wanted conversational and got formal, your context was unclear.
- Does it match your examples? If your example showed code with inline comments and AI excluded comments, you didn't show enough examples.
- Can you reuse this prompt? If you'll only use it once, it's fine. If you'll use it 100 times, refine it until it's perfect.
Build Yourself a Prompt Library
The habit that's saved me the most time isn't writing a great prompt once — it's saving the ones that worked and reusing them as templates. A small library covering the recurring jobs (API endpoint docs, explaining a technical concept, generating code examples, a troubleshooting guide, a migration guide) means you're editing a proven template instead of starting from a blank page every time.
A few things I'd genuinely stand behind after doing a lot of this: small wording changes really do produce noticeably different output, so it's worth treating a prompt like something you iterate on rather than something you get right the first time. Telling the model who the audience is tends to matter more than almost anything else you can add — far more than piling on adjectives like "good" or "professional." And showing an example of the exact tone and format you want is more reliable than describing it in the abstract; models are better at matching a pattern than interpreting an adjective.
None of this replaces editorial judgment — you still have to read the output closely enough to catch what's subtly wrong, which is a different skill than writing the prompt in the first place. But a well-built prompt cuts down dramatically on the editing you'll need to do afterward, and that gap between a vague prompt and a considered one is, in my experience, the single biggest lever available to a documentation team using these tools today.