Re: Documentation epub format - Mailing list pgsql-hackers

On Wed, May 01, 2013 at 09:33:23AM -0700, Joshua D. Drake wrote:
> 
> On 05/01/2013 09:27 AM, Fabien COELHO wrote:
> >
> >
> >Hello devs,
> >
> >I've given a try to the PostgreSQL documentation in epub format.
> >
> >I must admit that there is a bit of a disappointement as far as the user
> >experience is concerned: the generated file is barely usable on an iPad2
> >with the default iBooks reader, which was clearly not designed for
> >handling a "4592" pages book (from its point of view).
> >
> >The table of contents too much detailed, so it is long and slow to scan,
> >and there is no clear shortcut. Flipping pages in the documentation
> >takes ages (well, close to one second or more if I flip a few pages). Do
> >not try "search".
> >
> >This seems to suggest that instead of generating one large ebook, the
> >build should generate a set of ebooks, say one for each part. At the
> >minimum, a less detailed toc could be more usable and help navigate the
> >huge contents.
> 
> Once upon a time we had multiple books as documentation, then at
> some point we merged them. It was quite a few years ago.
> 
> I would agree at this point that we need to consider breaking them
> up again. The documentation is unwieldy.

In my day job, we're building epubs that encompass entire college textbooks
(Physics, Algebra, etc.) There is in fact an issue w/ attempting to use
existing readers with such large files. There is a bit of a trap you can fall
into, though, limiting yourself to what the current generation of reading tools
(both software and dedicated devices) can do: newer devices will have greater
capabilities, and can make use of features of the content that only work well
in the context of the whole work. This happens right now when using the large
work on a less-mobile platform (though my new laptop is both mobile and more
capable than many db servers I've adminned in the past ...)

There are significant costs to splitting the docs up: both the author and the
reader have to agree on where a piece of information should live, and for the
(potentially naive) reader, this can be a problem. Structurally, I think since
the "one book to bind them" work has been done, there's much better
cross-referencing going on. In fact, that seems to be the reason for doing it.
If those xrefs can survive splitting into multiple docs, that can help relieve
the newbie-finding problem, though current reading tools may not support
linking across books, putting the burden of finding things back on the reader.

That said, creating a different format of the docs -- multiple epubs that are
more easily moved around and read on current devices -- has merit, if it
doesn't break the existing all-one-document presentation on the web. In that
sort of case, the multiple parts are a convenience, and have less burden to
carry for searchability and findability than if they are presented as the
primary format for using the material. If the split version is not primary,
automated, less-than-perfect means of splitting (page count?) can be
considered.

Ross
-- 
Ross Reedstrom, Ph.D.                                 reedstrm@rice.edu
Systems Engineer & Admin, Research Scientist        phone: 713-348-6166
Connexions                  http://cnx.org            fax: 713-348-3665
Rice University MS-375, Houston, TX 77005
GPG Key fingerprint = F023 82C8 9B0E 2CC6 0D8E  F888 D3AE 810E 88F0 BEDE