Table of contents for Fluid user manual

[Paul Zablosky]

This whole exercise of creating a virtual user manual has raised all 
sorts of interesting questions.  I'm delighted to see these things being 
discussed as the ToC evolves. Is it a release manual (our original 
objective), or a manual for people using any of the resources of the 
Fluid project (something it may be morphing into)?

I'm inclined to let it develop a bit, but keep discussion going on 
important issues, such as how we keep release-specific content 
distinguished from release-independent stuff -- the issue Anastasia 
addressed.  We'll need a few guidelines to keep things under control.  I 
offer the following for discussion:

   1. Content that is associated with the Fluid software releases should
      be readily identifiable  and easily found by the release
      consumers.  Right now we have it as the first sections of the
      ToC.  We should keep it this way until we come up with a more
      logical setup.
   2. Annotations should give the user an idea of what's on the page
      without clicking on it. We should always keep that in mind when
      composing or editing them.
   3. Section annotations should help the users decide if the material
      in the section is going to be generally of interest to them.
   4. The ToC should not have any child pages.  Pages with manual-only
      content should be attached to a central "Manual" parent page, if
      they have no other logical home.
   5. The ToC has now grown to about 2 1/2 scrollable screens in size. 
      At some point it may become unwieldy.  I have been toying with the
      idea of have cloakable sections but I'm not sure this is a good
      idea.  It would mean the user having to click rather than scroll.

What this whole scheme needs is some user testing.  Is it doing its job 
of making the Fluid reference material more accessible to consumers of 
the Fluid deliverables?  How can we find out? We may not be ready for 
that yet -- we may want to do a few more rounds of refinement first -- 
but it's something to keep in mind.

Paul

Colin Clark wrote:
> Allison,
>
> On 2-Jun-08, at 5:55 PM, Allison Bloodworth wrote:
>
>> I think the main impetus for adding this section was that we wanted 
>> to share out the results of the Content Management Research as a way 
>> of reporting on the state of UX in the Fluid communities (which I 
>> believe is one of the Fluid deliverables). After adding this, I 
>> realized that the results of the UX Walkthroughs are also something 
>> that we should probably share. I'm not entirely sure the OSDPL 
>> working group belongs there, but I added it at the last moment to 
>> publicize that effort and maybe it should be deleted. I guess the 
>> question is, who is the audience of the manual and would they find 
>> this information helpful (or conversely does the manual become 
>> overwhelming for most of our audience when it is included)?
>
>
> The audience question--will they find this particular information 
> helpful or overwhelming?--is exactly the right question, and one which 
> I'm unsure of the answer to.
>
> The nice thing about not freezing our documentation in PDF format is 
> that we can take some time to work out this question and change the 
> table of contents whenever we decide. :)
>
> Colin
>
> ---
> Colin Clark
> Technical Lead, Fluid Project
> Adaptive Technology Resource Centre, University of Toronto
> http://fluidproject.org
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20080602/413a9407/attachment.html>