Table of contents for Fluid user manual

Tue Jun 3 23:52:52 UTC 2008

I agree. We have the "release manual" material, which tracks the 
releases, and the "other user manual material" which is under constant 
development. My own feeling is that we should set up a single table of 
contents to reflect this.  The (virtual) user manual would comprise two 
sections, organized something like this:

   1. Release Manual
          * Component descriptions
          * API descriptions
          * Component-related tutorials
          * Release notes
          * Downloading
          * etc
   2. User Guide to Fluid
          * UX Toolkit
          * User Experience material
          * OSDPL material
          * VULab material
          * other exciting stuff

We're pretty close to this now.  I'd like to have only one ToC, just to 
give our readers a single starting place for their excursions through 
our documentation.  But I'm interested to hear other's opinions on this. 

Paul

Daphne Ogle wrote:
> Reading this thread, I keep wondering what other avenues we have for 
> letting the community know about Fluid UX projects that might be 
> useful to them (Higher Ed personas, content management use cases) yet 
> is not part of the release.  The release date doesn't put a stake in 
> the ground for this material as it does with components, APIs and the 
> such.  It is continuously growing and becoming more refined.  So in 
> that sense it doesn't really make sense for it to be part of a release 
> manual.  On the other hand, these things are a valuable deliverable 
> for the communities.  Do we need a separate jumping off point (perhaps 
> TOC) for UX Projects/Toolkit and deliverables? 
>
> -Daphne
>
> On Jun 2, 2008, at 4:37 PM, Paul Zablosky wrote:
>
>> 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 a age 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 
>> refinemen hing 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 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
>>>
>>
>> _______________________________________________
>> fluid-work mailing list
>> fluid-work at fluidproject.org <mailto:fluid-work at fluidproject.org>
>> http://fluidproject.org/mailman/listinfo/fluid-work
>
> Daphne Ogle
> Senior Interaction Designer
> University of California, Berkeley
> Educational Technology Services
> daphne at media.berkeley.edu <mailto:daphne at media.berkeley.edu>
> cell (510)847-0308
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20080603/a2a5834c/attachment.htm>