---
title: Man Pages For Your RubyGems
teaser:
tags: web,unix
author: Calle Erlandsson
published_on: 2014-11-01
---

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][0]
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)][2] for details).

The experimental generator we wrote is available [on GitHub][1], 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][1].

[0]: https://github.com/rdoc/rdoc
[1]: https://github.com/thoughtbot/rdoc-generator-mdoc
[2]: http://man7.org/linux/man-pages/man1/man.1.html