Whether I’m implementing an HTTP API client, using a Ruby library for the first time or installing a new dishwasher, I always appreciate well-written and correct documentation.
Besides being well written and correct, documentation also has to be accessible in order to be usable. Usable documentation is easy to find, parse and traverse.
The Unix manual is a good example of usable documentation. Instead of only being accessible over an internet connection, it already sits on your hard drive. In lieu of having unique formats, only viewable in special programs (that sometimes even have to execute arbitrary JavaScript code to generate the actual content), its pages have a common format and are optimized for presentation on an ASCII text display. This means you can view them pretty much anywhere.
When I’m writing C code, I get to enjoy having great documentation available in the form of man pages. I want this for when I’m writing Ruby as well.
As a first step in this direction, Mike Burns and I wrote an RDoc
generator that outputs man pages in mdoc(7) format: One for every module, class
and method. The produced man pages are viewable directly using man -l FILE or
using man [SECTION] PAGE after putting them in a directory on the $MANPATH
(see man(1) for details).
The experimental generator we wrote is available on GitHub, if you’d like to try it out. We see it as an experiment on whether man pages are a good fit for Ruby documentation or not. We want to share this with you to get your feedback on it and how it could be used.
Please share your thoughts and feedback on GitHub.