The work of technical writing has seen many evolutions over the last few years – particularly since the introduction of generative AI to the general public. Because of the nature of technical documentation, which contains both code and jargon that will be read by both specialists and LLMs, editing that writing can be a far more complex process than would be the case for more generalist writing.
For this reason, it can be useful for a writer to have Claude Code on hand to smooth out their work before they send it to a technical editor (particularly if they’re using the LLM to write their first draft, in any case).
Here are a set of prompts, categorised by function and order in which they should be run for maximum effect. I ran an abridged version of this process in “Can Claude Opus 4.8 Be Used by Technical Writers to Evaluate Their Own Work?” if you’re interested in seeing the results.
Note that you don’t have to run every single prompt; rather, I’ve ranked them in importance from most critical (3 asterisks***) to skippable-but-you-should-probably-do-it-anyway (1 asterisk*). Treat this as a library you can draw from, rather than a strict manual.
Stage 1: First Read / Triage
Run these first, on the whole draft, to decide where your editing time should go.
- What's the worst thing about this article in 8 words?***
- What's the worst big-picture thing about this article?***
- Where would a reader stop reading and close the tab? Quote the line.**
- Is this slop? Yes or no, with the evidence. (re-run in Step 5)**
Stage 2: Objective Pass
Does the thing work at all? Argument, structure, completeness? In a single session, run each sub-pass in order; the "ignore everything else" framing will keep Claude on one scope at a time.
2a. Structural
- Ignore logical errors, but identify any structural problems with this article.***
- Outline this article from headings and topic sentences only, so I can see whether the progression holds.***
- Does the intro promise something the body doesn't deliver – or vice versa?***
- Suggest where I need transitions; quote the abrupt jumps.**
- What questions will a reader have at the end of each section that I haven't answered?**
- What step, prerequisite, or assumption did I skip that a reader needs?**
- Which single section could be deleted with the least loss?**
- If you had to cut this by 30%, what goes first?**
- What's the title promising that the body underdelivers on?**
2b. Logical
- Ignore structural errors, but identify any logical errors in this article.***
- Act as a skeptical senior engineer. List every claim I haven't backed with evidence or an example.***
- What would a domain expert push back on hardest? Give me the strongest objections.**
- Where do I assert a 'why' but never actually explain it?**
- Is there an obvious counterargument I should acknowledge but didn't?**
2c. Technical accuracy
- Review every code block and command. Flag anything that wouldn't run as written or doesn't match the prose.***
- Flag any claim that may be outdated, version-specific, or that needs an 'as of' qualifier.**
- Are any statements oversimplified to the point of being wrong?**
- Is my terminology used consistently and correctly throughout?**
- Do my examples actually illustrate the point, or are they decorative?**
- What am I pretending to know but never actually demonstrate?**
- Are variable names, file paths, and outputs consistent across all code samples?*
2d. Spelling & grammar
- Identify any spelling and grammar errors in the article. ***
Stage 3: Qualitative Questions
What end result does the reader gain from your writing?
3a. Does it teach the reader something?
- Does this article have a clear narrative throughline?***
- Can the reader replicate any experiments or tasks performed in this article?***
- Does this article contain a final stance (or an explanation for the absence of one)?**
- → Based on these conclusions, does this article teach the reader something?***
3b. Does it make an impact?
- What is this article teaching the reader that they are probably wrong (or right) about?***
- What does the reader's journey look like from start to finish, summarised in 100 words?**
- Does the author maintain continuity in the points they make i.e. can the reader trust the author to know their own mind?**
- Grade the persuasiveness of this article from 1 (weak) to 5 (very persuasive).**
- → Based on these conclusions, does this article make an impact on the reader? Evaluate memorability, persuasion-to-action, and behavior change, and suggest any necessary fixes.***
3c. Is it compelling enough to hold a reader?
- How compelling is this article? Where did your attention flag?**
- What's the single most boring paragraph?**
- What's the one thing a reader will remember a week later? If nothing, say so.**
- Is the ending earned, or does it just stop?**
- → Based on these answers, will this article hold a reader's attention start to finish, and where is it most at risk of losing them?**
3d. Is it pitched right for the audience?
- My audience is [describe]. Flag anything too basic, and anything that assumes knowledge they won't have.***
- Find every undefined acronym or insider reference and tell me whether my audience would know it.**
- Where does the tone slip into condescending or over-their-head?**
- What would make a domain expert roll their eyes?**
- What's the one claim a reader is most likely to disagree with?**
- What's the biggest assumption I'm making about the reader that might be wrong?**
- If a non-native English reader hit this, which sentences or idioms would trip them up?*
- If a competitor wrote a takedown of this article, what's their opening line?*
- → Based on these answers, is this article pitched correctly for [audience] – too basic, too advanced, or right?**
3e. Does it read as human, not machine?
- What's the strongest LLM-flag?***
- What's the most generic sentence, one that could appear in any article on any topic?**
- Flag filler phrases and hedging with tighter replacements.**
- What's the most over-hedged statement, where I refuse to commit?**
- What's the laziest word choice here?*
- Describe the voice and tone in a few words – does it stay consistent?*
- Are there any sentences that say a lot but mean nothing?*
- → Based on these answers, does this article read as human-written, and what are the top three changes that would make it more so?**
Stage 4: Line Edit
Now the sentences – clarity and economy.
- What's the weakest sentence in this article?***
- What sentence is doing the least work?**
- Where am I telling the reader something instead of showing them?**
- Flag every sentence that took more than one pass to parse, and why.**
- Find the three longest, most overloaded sentences and propose splits.**
- Identify passive voice, nominalizations, and buried subjects, with rewrites.**
- Where am I explaining the same concept twice in different words?**
- Mark any paragraph too long to hold in my head at once and suggest a break.*
Stage 5: Copyedit & Proofread
Mechanical consistency, run last so you're not re-checking text you'll still change.
- List every consistency issue: heading capitalization, code formatting, list punctuation, product-name spelling, number formatting, straight vs curly quotes, em-dash spacing, Oxford commas, double spacing.***
- Ignore general errors – look only at inconsistencies like British vs US spelling and non-parallel structures (e.g. colons after some bullets but not others).***
- Check every hyperlink and cross-reference: does the link text match where it points?**
- Check that every figure, table, and code block is referenced in the prose and captioned in the same style.**
- Flag any misused homophones – its/it's, affect/effect, your/you're.*
Stage 6: De-sloppification
Below are a list of words that could flag AI-generated writing.
- Flag any instances of the following words, and suggest replacements.***
| Category | Words/Phrases |
|---|---|
| Verbs (action/marketing) | transform, revolutionise, unlock, elevate, leverage, empower, drive, offer, craft, resonate, deliver |
| Nouns (buzzwords & clichés) | synergy, paradigm shift, offerings, insights, value, gap (unless talking about actual space between objects), game-changer, noise (unless talking about literal noise), chaos, confusion, guesswork, clarity |
| Adjectives | scalable, data-driven, seamless, compelling, cutting-edge, robust |
| Adverbs/Qualifiers | quietly (unless talking about low volume), just, not, no, actually, genuinely, authentically, truly, exactly |
| Phrases/clichés | that matters / that works, real problems, cut through the noise |
Stage 7: Final Submission
No new prompts – re-run these two from Stage 1 on the polished draft. Repeat until you’re happy with the final text.
- What's the worst thing about this article in 8 words?***
- Is this slop? Yes or no, with the evidence.**
(That last one’s also a fun existential question for an LLM.)
You’ll obviously need to go through the final work yourself, but with this editing guide, you should be able to pick out the gnarliest errors yourself before you have to pass your work along.
Happy writing!