

Ask HN: examples of good library documentation? (or bad...) - gioele

I have been working for a while on a tiny Ruby gem that I extracted from some of my projects. I am quite happy with its code and its features, but before announcing it publicly I would like to write good documentation to it.<p>Having documented most of the methods of the main class I now understand that writing good documentation is hard. First of all it is hard to maintain a constant style in describing what a method do and what its parameters are when you are not a native English speaker. Then there are many little details that I keep changing daily because I feel that are not "right" (e.g., how to refer to the instance on which the method is running? "this instance"? "the current instance" "this"?). In general, the key problem is to understand exactly what needs explanation and which explanations should be avoided because they are state the obvious and only add weight to the prose.<p>So my question is: have you got examples of good library documentation? Documentation that you do not curse when you have to refer to it :), documentation that make really understand what you were looking for. Or, alternatively, have you got examples of documentation styles that should not be used?<p>(My library is at &#60;https://github.com/gioele/filepath&#62; and the live docs are at &#60;http://rubydoc.info/github/gioele/filepath/frames&#62;. Suggestions and patches are welcome.)
======
stonemetal
Sqlite has good documentation. It starts with intro code, follows with a few
good tutorials, then finishes with an Ok reference. It even has documentation
to help you decide when it is the right tool for the job.

Rake has some pretty bad documentation. It was obviously written by someone
who is familiar with the project and is a bit blind to the newbie perspective.
The tutorial contains obvious mistakes(look at tutorial one build.sh for an
example.)

