UX Toolkit Document -- PDF Version

[Paul Zablosky]

I have spent a number of hours looking at the documentation we're 
producing with through the "PDF export" of wiki pages, particularly the 
UX toolkit section.  Here are some observations.

   1. The wiki pages are reproduced as nicely paginated PDF images, with
      headings and page numbers.  The only organizing information in the
      heading, however, is the page title, so there is no indication of
      where the page comes from in the wiki hierarchy. There are no
      breadcrumbs to tell us whether this is a high-level overview page,
      or a child page containing details.  The page numbers are not much
      help, since they don't appear in the table of contents, and there
      is no way to create an index. 
   2. A table of contents is produced, reflecting the hierarchy of
      pages, but it doesn't contain any of the sectioning and headings
      we have used /within/ the pages -- only the page title -- making
      it not very useful.  It doesn't contain page numbers, so it's not
      much use for looking up content. In many Fluid pages, the page
      title is not as descriptive as it could be, authors having relied
      on in-page headings to indicate purpose and contents, worsening
      the problem.
   3. Pages are exported in the order of a tree walk of the wiki space,
      (using a pruned version of the space tree), so that pages come out
      in alphabetical order, rather than in the order they are described
      in the overview pages.  Even if we could change the ordering, the
      inability  to distinguish overview pages from sub-pages and
      sub-sub-pages will soon lead the reader into confusion. 
   4. Some of our pages have been enhanced to work well in the wiki
      environment. We have multi-column pages with right-hand sections
      containing related links, tables of contents, and meeting
      notices.  These serve as an excellent marginal gloss, enhancing
      the reader's experience with useful information.  In the PDF
      version they consume half the page (no %-width capability?) with
      most of their content useless to the reader.
   5. There is an inconsistency of style across our wiki pages.  Some
      are detailed and well-organized with clear narrative content,
      while others are simple collections of pointers to children.  This
      works well enough in the wiki, but looks rather odd when pages are
      serialized in print.
   6. There are other examples where PDF extractions of wiki pages work
      reasonably well.  The Confluence manual itself is such a beast. It
      does, however, work much better as a reference resource, where the
      reader is seeking a particular piece of information, rather than
      reading through a set of organized sections on a variety of topics.

All this sounds a bit negative.  I don't mean it to be so, I'm just 
trying to lay out the limitations of what we're working with here.  I 
had hoped that with a bit of juggling in the wiki I could make the 
serialized version a lot more readable, but I find myself stymied by the 
lack of ways to explicitly manifest the document's structure through the 
PDF extract process.

I'm wondering if I'm asking too much of the documentation effort.  I 
thought at first the objective was to produce a readable version of the 
Fluid Release documentation that a reader could print, and read through 
to gain an understanding of the UX toolkit.  It turns out to be really 
difficult to create pages that work well in the wiki, and which also can 
be serialized as a readable printed manual.  Perhaps a reconsideration 
of our goals and our target audience would be useful at this stage.  
[*Personal comment:* I really like to print off the manual for a product 
and sit down and read it to come to an understanding of how it works and 
what it's all about.  Well organized and coherently presented manuals 
give me a positive impression of the quality of the product.]

Having looked at the problem from a number of viewpoints, I'm appealing 
to the Fluid community for suggestions on how we should proceed. 
Consider the following questions:

   1. Is a printable manual really valuable to our target audience? 
   2. Can we achieve the quality of manual we want with the editorial
      resources we have available?
   3. Does it make sense to ask wiki-page authors to consider how their
      entries will work as serialized text with all the other pages --
      and possibly curtail their exploitation of the capabilities of the
      wiki? 

And some short-term considerations:

   1. Is there something we can do to add a little bit of organizing
      structure to the document?  Is there a technical approach I'm not
      aware of?
   2. Is there a way we could format page titles to be both more
      descriptive and also indicate their position in the hierarchy (as
      well as the order of presentation for child segments)?
   3. Should we try to think of the PDF version as something to be
      viewed with a PDF-reader, rather than a printable document?

In summary, let me say that the Fluid wiki pages contain a lot of 
well-presented and valuable information.  There is a room for editorial 
improvement -- wiki gardening is never at an end -- but the overall 
quality of the material is high.  Producing a coherent printed manual 
from the material, however, is a challenge that our technical tools 
aren't quite up to.  We have to consider what we can do about this.

I'm really interested to hear what everyone thinks about this.

Paul





-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20080515/4a22a9cf/attachment.html>