4 ms·
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 li
by inphovore 4y ago
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 crowded) sentences. These tend to always write as though they’re explaining to an intelligent child (with a pleasant unassuming and direct simplicity.)
- maxekman 4y agoGood suggestion! Do you have any technical docs that stand out as extra good in your opinion?
- inphovore 4y agoI remember the Ansible docs as pretty good. 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.
- taubek 4y agoStripe is very often mentioned as an example of great docs - https://stripe.com/docs https://stripe.com/docs
- maxekman 4y agoThanks! Will definitely check that out. I know I have stumbled in there before, but not having used the service I have not really looked around too much.
- marginalia_nu 4y agoK&R, or anything else Brian Kernighan.
- maxekman 4y agoI had to look up what K&R was but makes sense after some searching. That book is probably worthwhile for lots of other reasons, even if I program in Go for most tasks. Thanks for the pointer!
- Fricken 4y agoSome are suggesting more reading, and others are suggesting more writing. I propose that it is best to do both, and maintain active feedback loops between the two.