I've asked a handful of people for recommendations on well-written/presented documentation for research & reference purposes:
- https://www.atlassian.com/git/tutorials/
- https://stripe.com/docs
- https://github.com/Shopify/javascript
- http://www.texample.net/media/pgf/builds/pgfmanualCVS2012-11-04.pdf
- https://pages.18f.gov/content-guide/
- https://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3/
- https://devcenter.heroku.com/categories/reference
Recommendation from folks on the GitHub docs team:
- Having a
README.mdfor your documentation directories (example: https://github.com/bernars/internal-docs-demo)- Titling those READMEs "What's in ______ directory?" (alleviating the need to be clever while still being friendly/helpful)
-
Updating existing docs is MUCH more difficult than writing them fresh. It's good to know that going in.
Processes change a lot. Usually (hopefully?) for the better, to make things easier. If you've written down a whole lot about how things work, VERY thoroughly, that info likely has a shelf life, and you're not going to be sure what needs to stay or go when (if) you go to update later on.
https://pages.18f.gov/content-guide/content-principles/#start-small-and-iterate
Put in a VERY basic structure. Make the structure simple and repeatable. Add more info as necessary. Don't use a whole bunch of screenshots in lieu of written steps. They get out of date SO FAST, and make your docs untrustworthy.
If you're describing how to use someone else's app, link to their docs rather than creating your own. All you need to do is describe what it is and why you're using it.
It is so easy for docs to become untrustworthy. That isn't an explicit feeling, either. People are rarely able to tell you, "I don't use that resource because I don't trust it," but that's the underlying problem every time.