10 ms·

Ask HN: Any great books about technical writing?

• nullandvoid 4y ago
  I've always found DigitalOcean to be a source of very high quality tutorials / documentation, and therefore think you can't go wrong with familiarising yourself with their guidelines https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines https://www.digitalocean.com/community/tutorials/digitalocea....
• jarkz 4y ago
  Docs for Developers: An Engineer’s Field Guide to Technical Writing https://a.co/d/cyI8Y15 https://a.co/d/cyI8Y15 HN thread: https://news.ycombinator.com/item?id=28948131 https://news.ycombinator.com/item?id=28948131
  • asicsp 4y ago
    More HN threads: "Tips for Writing a Technical Book" https://news.ycombinator.com/item?id=20070558 https://news.ycombinator.com/item?id=20070558 "How to write a programming book" https://news.ycombinator.com/item?id=23281568 https://news.ycombinator.com/item?id=23281568 "Learning technical writing using the engineering method" https://news.ycombinator.com/item?id=22283919 https://news.ycombinator.com/item?id=22283919 And a GitHub list: https://github.com/jenniferlynparsons/awesome-writing https://github.com/jenniferlynparsons/awesome-writing
• JHonaker 4y ago
  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/writing-docs-why-what-how/ https://eugeneyan.com/writing/ml-design-docs/ https://eugeneyan.com/writing/ml-design-docs/ https://reqexperts.com/wp-content/uploads/2015/07/writing_good_requirements.htm https://reqexperts.com/wp-content/uploads/2015/07/writing_go... https://eugeneyan.com/writing/what-i-do-before-a-data-science-project-to-ensure-success https://eugeneyan.com/writing/what-i-do-before-a-data-scienc...
• unexist 4y ago
  There are probably dozen of possible books, but I think this one matches your description perfectly: https://www.goodreads.com/book/show/34927405-living-documentation https://www.goodreads.com/book/show/34927405-living-document... Just for reference, here is a classic about writing in general: https://www.goodreads.com/book/show/53343.On_Writing_Well https://www.goodreads.com/book/show/53343.On_Writing_Well
• stunt 4y ago
  Google has a course for technical writing, and I think it's a good start. https://developers.google.com/tech-writing https://developers.google.com/tech-writing
• fabiom 4y ago
  Though not specifically targeted for developers, I recommend Steven Pinker's The Sense of Style. https://en.wikipedia.org/wiki/The_Sense_of_Style https://en.wikipedia.org/wiki/The_Sense_of_Style
• anonymousDan 4y ago
  Go buy grammarly pro as a starting point :)
  • anonymousDan 4y ago
    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 4y ago
  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 4y ago
  "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 4y ago
    ISBN-10 appears to be 0471807087. Amazon got it wrong.
• EddieDante 4y ago
  Strunk & White's The Elements of Style is a classic.
  • scruple 4y ago
    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 4y ago
    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.
• staccatomeasure 4y ago
  http://web.mit.edu/6.033/www/ http://web.mit.edu/6.033/www/ has links to a ton of really great examples of technical writing
• prcribeiro 4y ago
  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/ 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/ 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/ https://www.writethedocs.org/books/
• subpixel 4y ago
  Developing Quality Technical Information is a very good foundation: https://www.oreilly.com/library/view/developing-quality-technical/9780133119046/ https://www.oreilly.com/library/view/developing-quality-tech...
• sstevenshang 4y ago
  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 4y ago
    No. Good technical writing anicipates the questions that its readers willl have, and provides clear answers to those questions.
• wyclif 4y ago
  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 4y ago
    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 4y ago
      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 4y ago
  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.
  • rrishi 4y ago
    I am definitely looking forward to your bibliography. Leaving a comment so i can track it.
    • rodolphoarruda 4y ago
      Ugh, me too.
      • number6 4y ago
        And me too
        • noidesto 4y ago
          And me too
  • dont__panic 4y ago
    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.
    • 4y ago
• neves 4y ago
  I liked the approach of Pinker's book "A Sense of Style": https://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century 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.
  • neves 4y ago
    A good article about the book: https://www.openculture.com/2019/03/steven-pinkers-13-rules-for-good-writing.html https://www.openculture.com/2019/03/steven-pinkers-13-rules-...
  • udev 4y ago
    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 4y ago
  Put them all in a room and play On Writing Well by William Zinsser.
• kvch_ 4y ago
  I suggest reading Good With Words. The book good for any professionals who depend on effective communation. It is originally for created for lawyers, but it helped me tremendously at work as a software engineer. URL: https://www.fulcrum.org/concern/monographs/1v53jz538 https://www.fulcrum.org/concern/monographs/1v53jz538
• tshapedrob 4y ago
  Bugs in writing by Lyn Dupré
  • belter 4y ago
    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.
  • funcDropShadow 4y ago
    I've use this book countless times.
• beardicus 4y ago
  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-docs-as-a-product 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 4y ago
  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 4y ago
  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/orwell/essays-and-other-works/politics-and-the-english-language/ 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://docs.microsoft.com/en-us/style-guide/welcome/ https://developers.google.com/style https://developers.google.com/style
  • kqr 4y ago
    I agree. Taking advice from fiction writers I love has improved my technical writing more than anything else.
  • stinkytaco 4y ago
    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-seeing-his-stories-adapted-and-the-ever-expanding-popularity-of-sf/#.3xqvesdh0 https://electricliterature.com/the-legendary-ted-chiang-on-s...
    • halitherses 4y ago
      You may also enjoy hearing that Thomas Pynchon spent a spell as a technical writer at Boeing. I've only been able to dig up one of his articles [1]. I assure you that it's worth the read. [1] http://www.pynchon.pomona.edu/uncollected/together.html http://www.pynchon.pomona.edu/uncollected/together.html
• Minor49er 4y ago
  "How to Edit Technical Documents" by Donald W. Bush and Charles P. Campbell is a pretty easy read that explains how to approach writing and structuring technical documents. 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/dp/0897748700 https://www.amazon.com/Edit-Technical-Documents-Donald-Bush/...
• Denzel 4y ago
  The Minto Pyramid Principle is what you're looking for - https://www.amazon.com/NEW-Pyramid-Principle-Writing-Thinking/dp/B09W2VPVJX/ref=tmm_pap_swatch_0?_encoding=UTF8&qid=&sr= 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.
• amelius 4y ago
  My advice: just write your documentation in dry bullet-list format. Soon there will be tools based on GPT-3-like networks that can turn these into beautiful prose :)
• t66666666667 4y ago
  'Practical Software Requirements - A Manual of Content & Style' by Benjanin L. Kovitz, Manning, 1999 'The Science of Scientific Writing' by George D. Gopen & Judith A. Swan: https://www.usenix.org/sites/default/files/gopen_and_swan_science_of_scientific_writing.pdf https://www.usenix.org/sites/default/files/gopen_and_swan_sc...
• belfalas 4y ago
  I recommend everyone to read the SQLite documentation to see an example of excellence in technical writing. The other week a commenter here linked to this site as well: https://diataxis.fr/ https://diataxis.fr/
  • cratermoon 4y ago
    The Grand Unified Theory of Documentation also appears at Divio's site https://documentation.divio.com/ https://documentation.divio.com/ 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
• anjc 4y ago
  Not technical writing, but the best book I've ever read on writing (including Elements of Style etc.) is "Getting Published in International Journals: Writing Strategies for European Social Scientists". 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.
• satran 4y ago
  Not necessarily a technical writing book, but one for writing non fiction: On Writing Well, The Classic Guide to Writing Nonfiction by William Zinsser would be a very good read for everyone who wants to write.
• cromulent 4y ago
  Zen And The Art Of Motorcycle Maintenance is a classic, written by a technical writer, and touches on the subject at some length.
• tebeka 4y ago
  I found "Writing Without Bullshit" helpful. https://withoutbullshit.com/book https://withoutbullshit.com/book
• qznc 4y ago
  I find Donald Knuth an awesome technical writer: https://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematical_writing.pdf https://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematic... 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?
• curtis3389 4y ago
  Since nobody has mentioned it yet, for charts and graphs there's The Visual Display of Quantitative Information by Edward R. Tufte: https://amazon.com/Visual-Display-Quantitative-Information/dp/0961392142/ https://amazon.com/Visual-Display-Quantitative-Information/d...
• noufalibrahim 4y ago
  I don't know of any "how to write tech. books" kinds of books. I do have some recommendations of good examples of technical writing and right on top of the list is the C programming language closely followed by anything written by Brian Kernighan. The latters relaxed presentation with hard hitting examples drives home points in a way that no other book I've read does.
• namirez 4y ago
  Many years ago I used this as the textbook in a technical writing class: Booth, Colomb, and Williams, The craft of research, University of Chicago Press.
• sleepydog 4y ago
  The King’s English by Henry and Francis Fowler
• mobilene 4y ago
  I'm a Director of Software Engineering today, but early in my career I was a technical writer. 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.
• magicink81 4y ago
  Letting Go of the Words by Janice "Ginny" Reddish https://www.amazon.com/Letting-Go-Words-Interactive-Technologies/dp/0123859301 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!
• goopthink 4y ago
  "Write Useful Books" by Rob Fitzpatrick is an amazing guide for how to write, test, edit, and polish technical nonfiction.
• captainvic 4y ago
  There is a book titled "The Writing System" that as an engineer I found superb
• cratermoon 4y ago
  David Beer & David McMurrey, A Guide to Writing as an Engineer http://www.worldcat.org/oclc/1103219505 http://www.worldcat.org/oclc/1103219505 Philip Kiely, Writing for Software Developers https://philipkiely.com/wfsd/ https://philipkiely.com/wfsd/ Michael Alley The Craft of Scientific Writing http://www.worldcat.org/oclc/1032304610 http://www.worldcat.org/oclc/1032304610 Also see Online Technical Writing https://mcmassociates.io/textbook/ https://mcmassociates.io/textbook/ David McMurrey
• atmosx 4y ago
  I know ppl who are into technical writing that speak highly of this book: https://www.storytellingwithdata.com/ https://www.storytellingwithdata.com/
• tedyoung 4y ago
  Don't forget about diagrams! Words are important, but diagrams can really get concepts across. And not just the "technical" diagrams (sequence diagrams, flowcharts), but conceptual ones. I really like Abby Covert's new book on diagrams: "Stuck": https://abbycovert.com/stuck https://abbycovert.com/stuck
• carapace 4y ago
  Study E-Prime. > 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... https://en.wikipedia.org/wiki/E-Prime https://en.wikipedia.org/wiki/E-Prime
• MarinaMichaels 4y ago
  "Writing well" can mean two things: Putting together clear, concise, grammatically correct sentences that are pleasant to read; and organizing your content in a useful, rational way. Technical 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.
  • MarinaMichaels 4y ago
    Lisa Cron's book, _Wired for Story_, is aimed at fiction writers, but any type of writer can benefit from her book. She gives excellent cognitive-science-based reasons for each writing tip she gives. 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.
• skmurphy 4y ago
  This is an old one but a good one: Clear Technical Writing by John A. Brogan ISBN: 978-0070079748
• teleforce 4y ago
  Please check these two books on technical writing from Springer. 1) Docs for Developers: An Engineer’s Field Guide to Technical Writing https://link.springer.com/book/10.1007/978-1-4842-7217-6 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 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.
• gharman 4y ago
  Make It Clear by Patrick Henry Winston has a permanent place on my bookshelf. He breaks communication down into a structured system and applies it to a variety of forms including (beyond standard prose documents) things like decks, pitches, and lectures.
• chris-laffra 4y ago
  Not a book, but a comprehensive, introductory set of materials by the Google tech writing team: https://developers.google.com/tech-writing/overview https://developers.google.com/tech-writing/overview
• chris-laffra 4y ago
  C4E - Communication for Engineers. https://chrislaffra.com/c4e https://chrislaffra.com/c4e 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]
• aloci 4y ago
  My top recommendations are "Docs for Developers" and "The Product is Docs". I listed more books about docs and general writing, and TW courses and podcasts in this post: https://lorenaciutacu.com/resources-technical-writers/ https://lorenaciutacu.com/resources-technical-writers/
• muchas_gracias 4y ago
  The Elements of Style by Strunk and White is a short book of "rules" about style which boil down to making every word, letter, and punctuation mark "tell." I believe it to be essential to begin writing clearly and effectively.
• rekabis 4y ago
  Not a book on technical writing per se, but Writing Without Bullshit (https://www.amazon.ca/dp/0062477153 https://www.amazon.ca/dp/0062477153) can bring immense clarity and purpose to your writing. De-bloating prose is essential to good technical writing, and this book teaches you that.
• deleted 4y ago
  [deleted]
• ijustwanttovote 4y ago
  Google just released a tech writing course https://developers.google.com/tech-writing/overview https://developers.google.com/tech-writing/overview