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
_______________________________________________
fluid-work mailing list
[email protected]
http://fluidproject.org/mailman/listinfo/fluid-work
