Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Any great books about technical writing?

news.ycombinator.com

Post reply on HN
Print view View original

61–70 of 87 posts

Re: Ask HN: Any great books about technical writing?

#61

Post by throwaquestion5 »

pivic wrote: post #20

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.

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 :)

Re: Ask HN: Any great books about technical writing?

#63

Post by halitherses »

stinkytaco wrote: post #39
thenerdhead wrote: post #28

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…

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/t…

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

Re: Ask HN: Any great books about technical writing?

#65

Post by tedyoung »

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

Re: Ask HN: Any great books about technical writing?

#66

Post by anonymousDan »

anonymousDan wrote: post #8

Go buy grammarly pro as a starting point :)

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).

Re: Ask HN: Any great books about technical writing?

#68

Post by cratermoon »

belfalas wrote: post #40

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/

The Grand Unified Theory of Documentation also appears at Divio's site 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

Re: Ask HN: Any great books about technical writing?

#69

Post by MarinaMichaels »

"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.

Re: Ask HN: Any great books about technical writing?

#70

Post by MarinaMichaels »

MarinaMichaels wrote: post #69

"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 t…

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.

Post reply on HN