October 2012 Archives

Different View on Documentation

The actual intention behind perlybook.org was to make module documentation from CPAN more portable. Ebook-Readers today are designed for reading-pleasure everywhere - in your garden at daylight or in your bed at night... and this works so far.

But recently I noticed an effect which could also be of interest for "normal" Perl programmers who just work at a the computer and also prefer reading the docs there.

I always found it a bit complicated to read documentation on CPAN. If the author does not give a lot of love to the documentation it's even complicate to browse through all the docs of each module, since there is no auto-generated TOC over the complete distribution (only on inside each modules doc).

But there are even more issues.
See how the documentation of EBook::MOBI looks like on my screen (1920x1080):

CPAN_small.jpg

This is what you see first. It is a horrible layout, isn't it? You have so much unused space and the TOC is so big that you don't see what you are probably most interested in... a small description and the example in the SYNOPSIS.

About perlybook

user-pic This is about perlybook, a webservice that lets you create Perl module documentation in ebook formats.