"Design the architecture, name the components, document the details." - Rob Pike
Good documentation requires there to be good code underneath it IMO. If your code is confusing and hard to follow your docs will be the same since they will have to break all of that down.
Some rules of thumb I follow when writing my docs:
- Document what it does not how it does it (exceptions possible here as sometimes how something happens is important but not always). The how will probably change over time. The what will likely stay the same.
- Doc strings n all public methods are written with a user in mind. If was using my lib in a Python shell and I didn't know what to do what would I want to see if I called `help(foo.func)`.
- Doc strings for "private" (Python doesn't really have private but components with leading underscores are meant to be left alone) are written with other contributors to the code base in mind. They will have some more reasoning to them as to the hows and whys since they may need to know how to interact with this component at a lower level than the public API.
- If you are using a dynamic language make sure you add type information for parameters and return values. Document what exceptions will be raised and what cases they will raised in.
- I like reading code more than docs so most of my documentation includes examples of how to use something. Not every piece of code lends it self well to this but if you can do it, do it.
- Tests are an outstanding form of documentation. I'll usually look at a packages tests before the docs to see how it works.
These are all very subjective of course. I've used packages that I thought had great docs and others thought they were terrible. Here's an example of some of the things I described here:
https://im-auld.github.io/httpbase