11–20 of 162 posts
Earlier quoted context omitted.
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
Stripe is very often mentioned as an example of great docs - https://stripe.com/docs
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?
Earlier quoted context omitted.
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
K&R, or anything else Brian Kernighan.
It’s no different than writing code or writing a book. It takes time, iteration, and focus.
Personally happy to review a doc or two and provide feedback if that is helpful. I run a docs site for my company.
And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...
It's a much better experience and result than reading on a screen, editing it while you're reading, getting distracted, jumping back and forth between doing other things.
After writing a lot of text, print it out, take it outside if the weather's nice, put away your laptop, tablet, and phone, sit down with a pen, read over the entire document, and mark up the paper with your pen. It's a much better experience and result than reading on a screen, editing it while you're reading, getting distracted, jumping back and forth between doing other things.
The best way in my opinion is to write, and write more. Once you write your first doc, send it to someone who you believe may be your target audience and have them critique it. What’s confusing to them? What’s not? It’s no different than writing code or writing a book. It takes time, iteration, and focus. Personally happy to review a doc or two and provide feedback if that is helpful. I run a docs site for my company…