Hacker News new | ask | show | jobs
by yrui 1460 days ago
I'm from a hybrid humanities and technical background. Good writing is good writing: clear, simple, and easy to read.

Books that influenced me:

Style, by F.L. Lucas

Simple and Direct, by Jacques Barzun

For technical writing, I recommend four additional disciplines:

1.) Keep the documentation up to date.

2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this. Also, re-read what you wrote periodically, and make revisions whereever you think you can improve clarity and usefulness.

3.) Provide copious examples where you show how to accomplish useful things.

4.) Use the tool you're documenting. Find errors, corner cases, and things to be aware of and document them as comprehensively as possible.

1 comments

I second the "Simple and Direct" recommendation. I stumbled upon it in a book store over a decade ago and I've never seen anyone recommend it before. Years after reading it, I still hear the author's recommendations in my head when writing.