Skill.re
AI for Technical Writing That People Actually Read
Bad Writing Wastes Everyone's Time
You're onboarding a new engineer. You point them to the "How to deploy" documentation. It was written three years ago by someone who's since left the team. It's unclear. It has outdated steps. It references internal systems that have changed. The new engineer spends two hours figuring out the actual deployment process through trial and error. Next quarter, another new engineer does the same thing. You've just burned 40+ hours of engineering time because documentation was bad.
Bad documentation is worse than no documentation. No docs say "we don't document this." Bad docs say "we documented this but we didn't do it well," and people waste hours fighting unclear instructions.
Good documentation is clear, concise, well-structured, has examples, and is actually accurate. Writing good documentation takes effort, especially for technical people who aren't trained writers. This is where AI helps tremendously. Not to write documentation for you, but to make writing good documentation actually practical.
What AI is Genuinely Good At (In Writing)
- Taking messy notes and structuring them logically. You brain dump everything. AI organizes it.
- Clarifying unclear explanations. You explain something poorly. AI rewrites it clearly.
- Removing jargon and technical obfuscation. You use domain-specific terminology. AI translates to simpler language without losing precision.
- Generating examples. You describe how something works. AI generates realistic examples.
- Creating appropriate outlines and TOCs. You're writing a guide. AI suggests logical structure.
- Editing for clarity and flow. Your first draft is choppy. AI smooths it.
- Adapting tone for different audiences. Same content, different audience = different tone. AI adapts.
- Filling in explanatory gaps. You skip something "obvious." AI identifies and fills the gap.
What AI is NOT Good At
- Correctness without review. AI can hallucinate. Always verify technical content.
- Domain-specific expertise. It doesn't understand your system's actual architecture without you explaining it.
- Tone matching your actual voice. It can approximate. You need to adjust to sound like yourself.
- Knowing what matters to your audience. You need to tell it what your reader cares about.
The AI-Assisted Writing Workflow
Step 1: Brain Dump (5-10 minutes)
Write down everything you want to say. Don't worry about clarity, structure, or quality. Just get it out of your head into a document. Use bullet points, fragments, whatever. The goal is capture, not polish.
Example: "I need to document our payment processing system"
Brain dump:
- We use Stripe
- We have idempotency keys so same payment doesn't process twice
- There's webhook handling for confirmations
- Failed payments go to a retry queue
- We log everything to audit trail for compliance
- There's a dashboard thing that shows payment status
- Sometimes payments take a while, we have async stuff
- If webhook doesn't fire, we have a reconciliation job that checks
- The reconciliation runs every 6 hours
- I don't remember if there's rate limiting with Stripe
- We soft delete payments, not hard delete
- There's some multi-currency stuff but it's new
Step 2: Ask AI to Structure It (5 minutes)
Prompt:
"I need to document our payment processing system. Here's everything I know:
[BRAIN DUMP]
Who needs this doc: Backend engineers integrating payment processing, support team troubleshooting payment issues.
Create an outline that makes sense for these audiences. What sections should we have?"
The AI creates a logical structure. You get something like:
- Overview: What the system does
- Architecture: How it's built (Stripe integration, async processing, idempotency)
- Processing Flow: Step-by-step what happens when a payment comes in
- Webhook Handling: Real-time confirmations and error handling
- Retry Logic: What happens when payments fail
- Audit & Compliance: How we track for compliance
- Troubleshooting: Common issues and how to debug
- Dashboard: Monitoring payment status
Step 3: Fill in Each Section (15-30 minutes)
For each section, write a rough explanation. Don't worry about polish. Just explain it like you're talking to a colleague.
Section: "Processing Flow"
Rough explanation:
- Payment comes in from [where]
- We check if it's a duplicate using idempotency key
- If new, we send to Stripe API
- Stripe returns a payment ID
- We create a payment record in the database with status "pending"
- Then we wait for webhook confirmation
- If webhook comes in, we mark it confirmed
- If no webhook after 6 hours, reconciliation job checks with Stripe
Step 4: Ask AI to Clarify and Expand (10 minutes)
Prompt:
"Here's my rough draft of a section about payment processing:
[YOUR ROUGH DRAFT]
Please:
1. Rewrite this for clarity
2. Remove jargon where possible (explain terms if necessary)
3. Add a concrete example of what happens for a successful payment
4. Add a concrete example of what happens if the payment fails
5. Highlight any potential issues our team should be aware of"
The AI expands it with examples and clarification. You get something readable.
Step 5: You Edit and Verify (10-15 minutes)
Read the AI output. Is it accurate? Did it miss anything important? Did it explain something wrong? Fix it. Add specifics it got wrong. Remove anything not applicable.
This is the critical step. You're not writing from scratch. You're editing an AI draft. Much faster.
Step 6: Get Feedback and Iterate (5-10 minutes)
Share it with someone else on the team (or your future self). Ask: "Does this make sense? What's confusing? What's missing?" Make adjustments.
AI Works Differently for Different Documentation
API Documentation
AI is excellent at this. You provide:
- Endpoint URL and HTTP method
- What it does
- Required parameters
- Example request and response
- Error cases
AI generates clean, professional-looking API docs with examples. Usually requires minimal editing.
Runbooks (How to Respond to X)
AI helps structure but needs heavy review. You provide:
- What the problem is
- How to detect it
- Step-by-step diagnosis steps
- Possible fixes
- How to verify fix worked
- Who to escalate to if stuck
AI creates a structured runbook. But you must verify steps actually work. Walk through the runbook before publishing.
Architecture Documentation
AI is okay here. Provide:
- System diagram (describe it or paste ASCII art)
- What each component does
- How they communicate
- Key decisions and why they were made
- Trade-offs considered
AI writes good descriptions. But verify technical accuracy and add nuance about trade-offs.
Onboarding Documentation
AI is very helpful. You provide:
- What a new engineer needs to understand
- In what order they should learn it
- Common gotchas and confusions
- Tools they'll use
- Who to ask for help with what
AI creates a structured onboarding guide with explanations. Update it once per quarter as your system evolves.
Using AI to Improve Existing Docs
Your documentation is outdated. Rather than rewrite from scratch, use AI to improve what you have.
Prompt:
"Here's our current documentation for [SYSTEM]:
[PASTE CURRENT DOCS]
Issues:
- Last updated [WHEN]
- It doesn't explain [WHAT]
- It references [OLD THING] that we don't use anymore
- The [SECTION] is confusing
Please:
1. Update it for current practices
2. Clarify the confusing sections
3. Remove references to old tools
4. Add an example of [SPECIFIC SCENARIO] that people always ask about"
AI creates an improved version. You review and finalize.
The Documentation Clarity Checklist
Before publishing, ask the AI to review your docs against this checklist:
Documentation Quality Checklist:
- Clarity: Can a reader unfamiliar with the system understand this? Or does it assume too much knowledge?
- Structure: Is it organized logically? Does the reader understand what comes first?
- Examples: For every concept, is there a concrete example?
- Completeness: What questions will readers have? Are they answered?
- Currency: Is this still accurate? Or is there outdated information?
- Scannability: Can someone quickly find what they need? Are section headings clear?
- Jargon: Is technical jargon explained? Or would someone new not understand?
Real Examples of AI-Assisted Writing
Example 1: Documenting a Payment API Endpoint
You have: A Stripe integration endpoint that's been working for two years. No documentation. Engineers keep asking how to use it.
You do: Brain dump the endpoint behavior. Ask AI to structure it. You fill in details and examples. AI cleans it up.
Result: Professional API docs that engineers can actually follow. Takes 30 minutes instead of 2 hours of writing time.
Example 2: Creating an On-Call Runbook
You have: Years of experience handling "payment processing is slow" issues. New engineers don't know how to debug this.
You do: Write down how you'd diagnose it (check queue depth, check Stripe latency, check database queries). Ask AI to structure this as a runbook with step-by-step diagnostics. You verify each step actually works.
Result: New on-call engineer can follow the runbook and solve the issue without waking you up at 3am.
Example 3: Updating Outdated Architecture Docs
You have: Architecture documentation from two years ago. You've since migrated from monolith to microservices. The old docs are confusing.
You do: Paste the old docs, describe what's changed, ask AI to update it. You review for accuracy.
Result: Current docs that new people actually use.
Case Study: Engineering Team Documentation Overhaul
A 50-person engineering team had significant documentation debt. Estimation: 300 hours of writing and organizing docs. Reality of writing from scratch: it wouldn't happen. Instead, over Q2 2024, they used AI-assisted writing to accelerate documentation. Process: Every engineer who owned a system (payments, auth, notifications, data pipeline, etc.) spent 3 hours on their system's documentation. Brain dump (30 mins) → AI structure (10 mins) → fill in sections (90 mins) → AI clarify (10 mins) → review and finalize (40 mins). Total: ~3 hours per engineer for solid documentation. 15 engineers participated. 15 critical systems documented. Comparison: hand-writing would have taken 20+ hours per engineer. Time saved: 255 engineer-hours. Dollar value (at $150/hr burdened): $38,250. Cost of AI tools: $500 for quarter. Documentation quality (measured via employee survey post-implementation): 72% said docs were "useful or very useful" vs. 18% pre-implementation. Impact on onboarding: new hires reported "had to ask questions" dropped from 85% to 45%. The documentation became self-sustaining after initial creation because adding new docs became part of the change process (document what you build).
Common Mistakes in AI-Assisted Writing
Publishing without reviewing for accuracy: The AI might sound confident and wrong. Always verify technical content. Walk through the examples. Make sure they actually work.
Not including enough context: "Document this API" produces generic docs. "Document this payment API that integrates with Stripe and uses idempotency keys for deduplication, integrating with our async queue for processing" produces useful docs.
Over-relying on AI for complex systems: AI can structure and clarify. But if your system is complex, you need to explain the complexity clearly. AI won't invent details.
Letting docs get outdated: Documentation debt is worse than code debt. Someone reads it and it's wrong. They trust it because you published it. Plan to review docs quarterly. Use AI to update them efficiently.
Writing for the wrong audience: Tell the AI your audience: "These docs are for backend engineers, not product managers." AI adjusts tone and content accordingly.
Real Workflow Example: A team documents their notification system. Brain dump takes 10 minutes (all the ways notifications can fail, how retries work, how the queue works). AI structures it (Overview → Architecture → Processing Flow → Error Handling → Troubleshooting). Team fills in details (5 minutes per section). AI clarifies and adds examples (3 minutes). Team reviews for accuracy (10 minutes). Total: 45 minutes for docs that would have taken 3 hours to write from scratch. Done.
Making Docs Part of Your Process
Documentation falls apart because no one owns maintenance. Fix it by making docs a normal part of work:
- When you deploy a change, update the docs. It takes 5 more minutes. Do it then, not later.
- When someone asks a question, document the answer. If it's asked once, it'll be asked again.
- During quarterly planning, dedicate time to docs. One engineer, one week, reviewing and updating all docs.
- Link docs from your code. If code references a runbook or architecture doc, link to it. Dead links become obvious.
Key Insight
Good documentation saves time constantly. Bad docs waste time constantly. AI makes writing good docs practical, not aspirational. Use it to turn the docs you should write but won't into the docs your team actually uses.
What to Do Monday Morning
- Identify one critical system lacking documentation. Your payment processing, auth flow, deployment process, etc.
- Brain dump everything you know about it. Bullet points, fragments, all of it. 10 minutes max.
- Ask the AI to structure it. "Create an outline that makes sense for [audience]."
- Fill in each section with rough explanations. Don't polish. Just explain.
- Ask the AI to clarify and add examples. Let it clean up your rough sections.
- Review for accuracy and adjust tone. Does it sound like you? Is it technically correct?
- Share with a teammate. Ask: "Does this make sense? What's confusing?"
Frequently Asked Questions
Q: Doesn't using AI to write documentation make it less authentic or personal?
The AI is a tool to help you write faster and clearer. Your voice and judgment are still in the docs. You're just not spending three hours formatting and reorganizing. If your docs feel impersonal, adjust the tone. That's not an AI problem, that's an instruction problem.
Q: How do I make sure the examples in the docs are correct?
You verify them. Walk through each example yourself. Try it. Make sure it actually works. The AI might generate an example that looks right but has a subtle bug. Your job is to catch that.
Q: What if the AI misunderstands our system?
Then you explain more clearly. "That's close but not quite. Here's what actually happens..." and the AI adjusts. It learns from your corrections. This is why editing is faster than writing from scratch. You're correcting mistakes, not generating everything.
Q: Should we document everything or just critical systems?
Start with critical path. If people ask about it repeatedly, document it. If people get it wrong frequently, document it. If it's complicated or not obvious, document it. You don't need docs for "here's a standard REST endpoint that does what you'd expect."
Q: How often should we update documentation?
At minimum quarterly. More realistically: whenever something changes significantly. If you're not reviewing docs every quarter, they're getting stale. Set a calendar reminder.
Q: Won't AI-generated documentation feel generic or like every other company's docs?
Only if you let it. The AI is a tool to organize and clarify your thoughts, not to replace your voice. If your docs feel generic, you're not providing enough specific information. "We use Stripe for payments" is generic. "We use Stripe with idempotency keys for deduplication, retries after 5 seconds, and webhook-driven reconciliation every 6 hours" is specific. Put the specifics in, and the AI will preserve them while making them clear.
Q: What if our system is so custom that AI can't understand it?
Then you explain more detail in the brain dump. "We have a custom queue system we built that..." Give the AI enough detail and it will structure it well. The AI's job isn't to understand your system. It's to organize what you tell it about your system. You provide understanding. AI provides structure.
Q: Doesn't this approach mean we're relying on AI to get documentation right?
No. You're still responsible for correctness. AI is a tool to speed up the structuring and clarifying parts. You're still the expert doing final review. This is editing, not abdicating responsibility. If you're not reviewing the output carefully, AI-assisted writing won't work.
Q: Should internal documentation look different from customer-facing documentation?
Yes. Internal docs can be more technical and assume more context. Customer-facing docs need to be more careful about jargon and more focused on user problems. Tell the AI your audience and it adjusts accordingly: "This is for backend engineers" vs. "This is for product managers." Same information, different presentation.