Table of contents for Fluid user manual

[Colin Clark]

I also like this approach. Great idea, Paul.

Colin

On 4-Jun-08, at 1:05 PM, Daphne Ogle wrote:

> +1  This sounds like a great structure to meet our goals of easy  
> access and the distinction between the kinds of deliverables we are  
> offering.
>
> -Daphne
>
> On Jun 3, 2008, at 4:52 PM, Paul Zablosky wrote:
>
>> 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:
>> 	• Release Manual
>> 		• Component descriptions
>> 		• API descriptions
>> 		• Component-related tutorials
>> 		• Release notes
>> 		• Downloading
>> 		• etc
>> 	• 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:
>>>> 	• 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.
>>>> 	• Annotations should give the user a age without clicking on it.  
>>>> We should always keep that in mind when composing or editing them.
>>>> 	• Section annotations should help the users decide if the  
>>>> material in the section is going to be generally of interest to  
>>>> them.
>>>> 	• 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.
>>>> 	• 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
>>>> http://fluidproject.org/mailman/listinfo/fluid-work
>>>
>>> Daphne Ogle
>>> Senior Interaction Designer
>>> University of California, Berkeley
>>> Educational Technology Services
>>> daphne at media.berkeley.edu
>>> cell (510)847-0308
>>>
>>>
>>>
>>
>
> Daphne Ogle
> Senior Interaction Designer
> University of California, Berkeley
> Educational Technology Services
> daphne at media.berkeley.edu
> cell (510)847-0308
>
>
>

---
Colin Clark
Technical Lead, Fluid Project
Adaptive Technology Resource Centre, University of Toronto
http://fluidproject.org