HN Explorer

Ask HN: Any great books about technical writing?

161 points by iluzone ↗ HN
Im looking for a resources (ideally books) that can help juniors, devs and even seniors to improve their technical writing. To help them write better issue descriptions, announcements, documentations, user manuals and so on. How to communicate (in a written form) technical stuff to technical and non-technical people.

86 comments

[ 3.2 ms ] story [ 169 ms ] thread
jarkz
Docs for Developers: An Engineer’s Field Guide to Technical Writing https://a.co/d/cyI8Y15

HN thread: https://news.ycombinator.com/item?id=28948131

JHonaker
I second the request. I think communication is a drastically underappreciated skill even though we have all suffered due to poor communication professionally (undocumented libraries, poorly specified requirements, an inability to generate buy-in for our ideas).

I'll throw in a few recommendations I have from some recent research at work:

https://eugeneyan.com/writing/writing-docs-why-what-how/

https://eugeneyan.com/writing/ml-design-docs/

https://reqexperts.com/wp-content/uploads/2015/07/writing_go...

https://eugeneyan.com/writing/what-i-do-before-a-data-scienc...

anonymousDan
Go buy grammarly pro as a starting point :)
anonymousDan
No idea why this got downvoted - most people's writing is so full of basic grammatical errors and bad habits they don't even realise they have. Finding such examples in your own writing is a great way to improve in my experience (whatever automated tools you choose).
lbriner
I think the thing that helped me most was simply to learn more about English (I am a native English speaker) so that I could get an understanding of consistent tense, tone, narrative etc.

I suspect there are good general books on English writing but now I have learned how to write better, I can't believe I found it so difficult before.

jnxx
"Effective Writing for Engineers, Managers, Scientists" by H.J. Tichy is the best book I have seen on the subject.

    Publisher:  ‎ Wiley-Interscience, 1988

    ISBN-10 ‏ : ‎ 9780471807087

    ISBN-13 ‏ : ‎ 978-0471807087
macintux
ISBN-10 appears to be 0471807087. Amazon got it wrong.
EddieDante
Strunk & White's The Elements of Style is a classic.
scruple
I keep a copy on my desk and thumb through it occasionally when I need help with my writing. Next to that book is also a copy of Williams and Colomb's Style: Toward Clarity and Grace. I've also read the USAF Tongue and Quill. There are good lessons in all 3 of these books for technical writers.
MDGeist
I got an MA in technical writing and my editing professor gave us Strunk & White. It probably did more for me than half the classes tbh.
prcribeiro
The Microsoft Style Guide is a useful resource for clearing up questions or obtaining recommendations on how to write most of the things you mention:

https://docs.microsoft.com/en-us/style-guide/welcome/

There are other style guides, of course. Check out this list at Write the Docs:

https://www.writethedocs.org/guide/writing/style-guides/

If you're searching for more generic information on how to communicate technical content effectively to different audiences, check out this list of recommended books:

https://www.writethedocs.org/books/

sstevenshang
Good technical writing is good writing. Just learn how to write well in general. I recommend going through The Elements of Style and basically any college level writing course materials.
t66666666667
No. Good technical writing anicipates the questions that its readers willl have, and provides clear answers to those questions.
wyclif
My AP high school English teacher taught me "garbage in, garbage out." His point was that if you want to write high level prose, you need to be reading the best prose stylists and be influenced by them. Read the best writers and stop reading garbage.
sramsay
English professor here. This is the secret to becoming a terrific writer: exposing yourself to excellent writing. Nothing replaces this, and it works in every genre from technical writing to lyric poetry.
wyclif
Who do you think are the best technical writers? I have a much better sense of who they are in literature, but in technical writing I'd like to read some examples.
pivic
I am a professional technical writer. When I started out, I desperately looked for tips and tricks. Internet was (and is) full of tips but I could not find a tech-writing bibliography.

I will soon publish a bibliography of books and guides regarding technical writing. I promise to paste a link here when I am finished, which I believe I will be in a day or two.

dont__panic
Commenting because I don't know a great way to find this comment in the future otherwise.

I have a decent learning & development stipend at my job, and I've been looking to buy some hard copies of technical writing books so I can refer to them easily during the workday. And to intimidate my enemies on Zoom, of course. So far my go-tos are "Docs for Developers" and the classic "Elements of Style", which complement each other well, covering the newest documentation strategies and the oldest nonfiction writing strategies, respectively. I'd really like to start posting reviews to my blog as I read more and build out my own library.

curiousgal
> Commenting because I don't know a great way to find this comment in the future otherwise.

You can favorite it.

sigstoat
> I don't know a great way to find this comment in the future otherwise.

click on the time of the comment and then bookmark the resulting page?

scottndecker
If you're that close to publishing just publish already :) This thread is dead in the next couple hours.
throwaquestion5
I just learned that tapping a comment's time let's you see the option for adding it to favorites. So thanks for that, and your future bibliography reference :)
neves
I liked the approach of Pinker's book "A Sense of Style": https://stevenpinker.com/publications/sense-style-thinking-p...

He gives writing tips based in how the mind works. Instead of a bunch of rigid rules, you can understand it based in cognitive theory.

udev
I read about 800 pages of his writing ("Better Angels ..." book) and there were passages of absolute beauty, like the part about Alan Turing.
euroclydon
Put them all in a room and play On Writing Well by William Zinsser.
tshapedrob
Bugs in writing by Lyn Dupré
belter
Second this recommendation. Very dense with lots of useful recommendations.

Only thing I cannot agree with, is the critique of Star Trek's motto and the suggested alternative. Does not have the same emotional connection.

beardicus
i am looking forward to this book _Designing Developer Documentation as a Product_ which should come out in 2023:

https://www.alejandraquetzalli.com/book-designing-developer-...

it might be a little more on the practical "nuts and bolts" side of things vs. "how do i write well", but it covers lots of areas that always seem to come up when producing documentation for developers.

Loughla
It doesn't answer your question, but for solutions that address the systemic issue at your organization, I offer two things that have been proven (in my life) to be effective:

First, without hiring more people, I would advise contacting your closest University and ask about graduate faculty who offer grant writing courses. For a small fee, they can provide training and materials for your staff.

Better, though, would be to target a non-technical grant writer and integrate that person into your team. Any communication for an exterior audience would flow through that person. I say non-technical, because that helps you avoid jargon and other "meaningless" items for exterior audiences. I also say specifically grant writer instead of technical writer because technical writers focus on ensuring all material is included, whereas grant writers also ensure that all material is digestible by human people. This person also learns your organization and can help target professional development for folks who might need it - it's all about creating a talent pipeline.

Source: I am a career grant writer, and any technical writing, especially areas as, for lack of a better word, arcane as tech writing can be vastly improved by succinct grant writers. I have contracted for companies in the past, but so few actually want to make systemic changes; mostly they want quick fixes and immediate solutions.

thenerdhead
I think all technical writing books are dry and boring.

The best books I've read that helped me with technical writing have been classic writing ones such as Ray Bradbury, Stephen King, Steven Pressfield, William Zinsser, and more.

Also following this general guideline from Orwell may help:

i. Never use a metaphor, simile or other figure of speech which you are used to seeing in print.

ii. Never use a long word where a short one will do.

iii. If it is possible to cut a word out, always cut it out.

iv. Never use the passive where you can use the active.

v. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.

vi. Break any of these rules sooner than say anything outright barbarous.

https://www.orwellfoundation.com/the-orwell-foundation/orwel...

You may also find some gems here and there with big tech companies developer documentation contribution style guides i.e.

https://docs.microsoft.com/en-us/style-guide/welcome/ https://developers.google.com/style

kqr
I agree. Taking advice from fiction writers I love has improved my technical writing more than anything else.
stinkytaco
Somewhat interestingly, Ted Chiang, in my opinion one of the best writers working in science fiction today, worked as a technical writer for Microsoft. However, he has said that they are very different and he doesn't feel one really impacts the other [1]. I'm not entirely sure I buy that, but it is interesting to see someone who's worked in both mediums talk about the connection.

[0]:https://electricliterature.com/the-legendary-ted-chiang-on-s...

Denzel
The Minto Pyramid Principle is what you're looking for - https://www.amazon.com/NEW-Pyramid-Principle-Writing-Thinkin.... A timeless book on how to structure writing. Once you understand it, you'll start to notice applications of the book out in the wild. You'll also start to loathe writing that isn't structured as such because it's needlessly tedious and more difficult to understand.

The Minto Pyramid Principle is heavily used and recommended within Amazon, a company famous for their culture of written narratives.