5 ms·
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
by maxekman 4y ago
Good 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!