Ask HN: Any great books about technical writing? 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. |
https://www.goodreads.com/book/show/34927405-living-document...
Just for reference, here is a classic about writing in general:
Edit: Some places have it priced pretty highly, but Amazon has it here for about $3:
https://www.amazon.com/Edit-Technical-Documents-Donald-Bush/...
'The Science of Scientific Writing' by George D. Gopen & Judith A. Swan: https://www.usenix.org/sites/default/files/gopen_and_swan_sc...
I really like Abby Covert's new book on diagrams: "Stuck": https://abbycovert.com/stuck
De-bloating prose is essential to good technical writing, and this book teaches you that.
https://www.amazon.com/Letting-Go-Words-Interactive-Technolo...
It is practical guidance that is durable over time. The book is exemplary of the advice on the pages. Plain language FTW!
On the surface it's aimed at academics who are non-native speakers of English, but in my experience most people could do with reading it.
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.
> E-Prime (short for English-Prime or English Prime, sometimes denoted É or E′) is a version of the English language that excludes all forms of the verb to be...
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.
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.
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.
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.
click on the time of the comment and then bookmark the resulting page?
You can favorite it.
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
[0]:https://electricliterature.com/the-legendary-ted-chiang-on-s...
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.
The Minto Pyramid Principle is heavily used and recommended within Amazon, a company famous for their culture of written narratives.
The #1 most important thing imho is know your audience. Who are you writing for? What do you know about them, or what can you reasonably successfully guess about them?
I once wrote a suite of manuals (yes, I'm that old) for an ERP software product. The audience was people on manufacturing shop floors, AP and AR people, sales people -- in other words, people who didn't know and didn't care about the underlying tech. They just wanted instructions to do their tasks. I learned their lingo and used it, and otherwise tried to write on a fourth-grade level.
At another company we wrote documentation that techs at wireline telephone companies used to install and operate our software. While these people weren't software developers, they were technical people and I wrote to them as such. I gave them the theory and concept behind things as well as the task instructions they needed.
"Tips for Writing a Technical Book" https://news.ycombinator.com/item?id=20070558
"How to write a programming book" https://news.ycombinator.com/item?id=23281568
"Learning technical writing using the engineering method" https://news.ycombinator.com/item?id=22283919
And a GitHub list: https://github.com/jenniferlynparsons/awesome-writing
The book discusses a variety of "soft" skills, including reading and writing. Not specifically focused on technical writing per se, but can still be very useful for engineers to learn how to influence others through written materials. As Urs Hölzle says in the foreword to the book:
"At some point in your career, you can no longer communicate effectively just by talking with others. Stand-ups, planning meetings, and peer programming sessions all have their physical limits. This effect applies to you sooner than you think. At that point, you need to switch to asynchronous communication techniques. In short, you need to switch to writing. Those who can write well suddenly have a head start. Through well-written communication, your influence suddenly grows exponentially."
[I am the author]
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:
The other week a commenter here linked to this site as well: https://diataxis.fr/
Some additional documents that don't fit neatly into the 4-document model are
Conceptual overviews, which are kind of like explanations but lean more towards the broader theories
Case studies, focusing on practical examples in use
FAQs are kind of a reference, focusing on common problems in usage
Troubleshooting guides can cover problems too uncommon for FAQs, but they usually presume a certain level of knowledge
Best practice articles are opinionated guides supplementing explanatory documents with additional guidance on why some solutions should be idiomatic
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...
Philip Kiely, Writing for Software Developers https://philipkiely.com/wfsd/
Michael Alley The Craft of Scientific Writing http://www.worldcat.org/oclc/1032304610
Also see Online Technical Writing https://mcmassociates.io/textbook/ David McMurrey
Publisher: Wiley-Interscience, 1988
ISBN-10 : 9780471807087
ISBN-13 : 978-0471807087Technical writing needs to do both, and it also needs to teach well.
Teaching well doesn't always mean you're writing well, and vice versa.
Teaching well means using what cognitive and learning scientists have discovered about how best to teach adults.
Books like Strunk & White's Elements of Style are good resources for putting together good sentences. Fewer books teach organizing your content, and even fewer teach how to teach well.
I'm an editor/book project manager at a major computer book publishing company, and a former software tech writer. I recommend Lisa Cron's book to all my authors.
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.
Skip the math stuff if you don’t need it, the rest is still worth it.
However, much better than reading about writing is getting direct feedback on your own writing. Maybe offer mentoring to your juniors?
1) Docs for Developers: An Engineer’s Field Guide to Technical Writing
https://link.springer.com/book/10.1007/978-1-4842-7217-6
2) Requirements Writing for System Engineering:
https://link.springer.com/book/10.1007/978-1-4842-2099-3
Currently there are 50% off until 29th August for selected books for back to school discount offering.