BUGS in writing
A humorous, practical guide to identifying and correcting common problems in technical and other forms of writing.
Stats for nerds
9recommend
13mentions
11people
2010–2026years
85% recommend15% neutral
Mentions per year
What Hacker News says
- our CLAUDE.md / AGENTS.md specifically calls out good engineering books, which I think does help:
From https://github.com/feldera/feldera/blob/main/CLAUDE.md:
- Adhere to rules in "Code Complete" by Steve McConnell.
- Adhere to rules in "The Art of Readable Code" by Dustin Boswell & Trevor Foucher.
- Adhere to rules in "Bugs in Writing: A Guide to Debugging Your Prose" by Lyn Dupre.
- Adhere to rules in "The Elements of Style, Fourth Edition" by William Strunk Jr. & E. B. White
e.g., mentioning Elements of Style and Bugs in Writing certainly has helped our review LLM to make some great suggestions about English documentation PRs in the past.
- Hi, former O'Reilly editor and current CTO here.
"Improve technical writing" is broad. First, I'd make sure everyone knows what kinds of docs it's possible to write. The Diátaxis Framework <https://diataxis.fr/> is good for that. Have a good discussion about what types of docs make sense for your environment -- who is the audience, what do they come with, what are they trying to do?
If they need help at the micro level of putting words together well, check out Lynn Dupre's "Bugs in Writing: A Guide to Debugging Your Prose" <https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...>.
If they're curious about the skills of a technical writer, Google has some good courses. <https://developers.google.com/tech-writing> We have had some first time tech writers and they identified this as a useful resource.
Structure is an overlooked aspect of writing -- we're familiar with alphabetical lists of API function names but this is only useful for reference material. Much of writing consists of modelling the reader in your head and structuring your prose so that you don't confuse that reader by talking about things before they're defined. Readers are a lot like simple compilers in that respect -- if you want to talk about something before it's covered in detail, you have to declare it first. A lot of becoming a good writer is just internalizing the literary smells for "this will confuse".
Like everything they want to improve at, your engineers need to attempt writing and then receive feedback on it. When I give people feedback, it's not just a rewrite -- I talk them through my changes, from language choice to overall structure, and explain why I made the change and think the change is better than the original. And if they wrote something particularly well, then I check they understand why it works.
Good luck!
- Bugs in writing by Lyn Dupré
- Have a look at a book called "Bugs in Writing" by Lyn Dupre'. Technical writers at Google recommend it. It's organized into more than a hundred short pleasantly readable chapters with each one focused on troubleshooting a specific issue. There's more to good writing than that, but at least you can get the small stuff resolved systematically. Disclaimer: I don't take everything in it as gospel but one has to start somewhere.
- Two things I recommend: the Google tech writing courses: https://developers.google.com/tech-writing
And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...
- A favorite of mine is the book BUGS in Writing, by Lyn Dupré (1998, Addison Wesley). It's a teach-by-example book with lots of examples she rates as ugly, bad, good, and even splendid.
