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.
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
man [SECTION] PAGE after putting them in a directory on the
(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.