1–10 of 162 posts
I have a fairly strong background in cloud system and application architecture. However I feel that I’m sometimes limited by my technical writing skills to communicate my ideas and concepts. Any advice on how to take ones technical writing skills to the next level?
I’m willing to do what it takes, being online courses, contributing to OSS process work or what else you might suggest.
Looking forward to tap into the HN hive mind on this topic!
Thanks, Max
Joseph M. Williams, Style: Ten Lessons in Clarity and Grace.
An old edition is fine. There are many editions with slightly differing titles (Toward Clarity and Grace, The Basics of Clarity and Grace), all of them are fine. Get the cheapest or fastest to deliver or whatever. Don't think about which one to get.
The other great book about writing is Thomas&Turner's Clear and Simple as the Truth. It teaches Classical Style, which is less fitting to technical documentation, as the authors discuss themselves.
The most effective way to improve your writing is through improving your reading.
I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never crowded) sentences. These tend to always write as though they’re explaining to an intelligent child (with a pleasant unassuming and direct simplicity.)
Technical writing benefits from Practical Style (the reader's time is important, the reader wants to get a job done, easy parsing of sentences is important), so I'd recommend one of the two best books about writing in English: Joseph M. Williams, Style: Ten Lessons in Clarity and Grace. An old edition is fine. There are many editions with slightly differing titles (Toward Clarity and Grace, The Basics of Clarity and…
Find good examples of well written documentation and emulate those. The most effective way to improve your writing is through improving your reading. I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never c…
Here's some technical writing courses: https://developers.google.com/tech-writing
And here are some examples of good writing: https://news.ycombinator.com/item?id=31630915
Find good examples of well written documentation and emulate those. The most effective way to improve your writing is through improving your reading. I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never c…
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
I’m sure you have read those great todo articles on medium or log rocket or whatever.
The problem with citing good professional documentation is that this is usually or inevitably taken on by a team, so docs are really a standard of a good editor.
The problem with stuff in the wild is it can be too bloggy or conversational.
What you need is awareness and purpose. Stop reading junk as soon as you identify it (skim junk for take always ;).
Cherish and reread somethings that “speak to you.”
Ironically, the best technical documentation is dry and to the point (without sounding as though generated from already inadequate code comments [glare].)
Edit out sarcasm, sentiments, and unnecessary references or language.
Explain what is happening, show an example and stop. You’ll do fine!
Do read one of those boring grammar/punctuation books. Just being aware of good sentence form will make you a better writer.
I did all this stuff over a decade ago, so I don’t have a link off hand.
Technical writing benefits from Practical Style (the reader's time is important, the reader wants to get a job done, easy parsing of sentences is important), so I'd recommend one of the two best books about writing in English: Joseph M. Williams, Style: Ten Lessons in Clarity and Grace. An old edition is fine. There are many editions with slightly differing titles (Toward Clarity and Grace, The Basics of Clarity and…
Find good examples of well written documentation and emulate those. The most effective way to improve your writing is through improving your reading. I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never c…
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?