Found in 4 comments on Hacker News
gnat · 2022-11-30 · Original thread
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!

gnat · 2022-06-25 · Original thread
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/...

drallison · 2015-02-01 · Original thread
I almost always find thoughtful discussion of how to write and convey ideas to be inspirational. Lyn Dupre's book, Bugs in Writing (http://www.amazon.com/BUGS-Writing-Revised-Edition-Debugging...) is good about some of the mechanics.

Likewise, thoughtful articles about how to structure and write good computer code are almost always interesting.

cubicle67 · 2010-10-01 · Original thread
I bought the first edition of Bugs In Writing (http://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/d...) years ago, and have found it an excellent reference.

It's aimed at technical writers and is a beautifully written book. Highly reccomended.

[Edit: I've just been reading the reviews on Amazon, and it seems a few people are put off by the 'cuteness' of the book, feeling it's not professional. The book has a strong personality (if a book can have such a thing) and lots of cat references/pics, so if you're likely to find that annoying it's not the book for you. Myself, I liked it]