Table of contents for Fluid user manual

[Anastasia Cheetham]

On 29-May-08, at 7:37 PM, Paul Zablosky wrote:

> I have created an initial version of a table of contents for the  
> Fluid release manual at http://wiki.fluidproject.org/x/VAAs.

Paul, this looks amazing! Thank you so much for this work.

> All the pages referenced in the ToC have been assigned the label  
> manual -- another way to locate them.

Excellent.

>   They include all the pages labeled "release" in the 0.3beta.

Seems to make sense. At first glance, the ToC looked rather long, but  
when I actually looked at the content, it seems quite reasonable.

> I invite comments and suggestions.  Does this seem like a useful  
> approach, now that we have an example?  Are there things I could do  
> to make the page and its contents more coherent and useful?

Paul, I have been working (and will continue to work today) on the  
technical documentation: APIs, tutorials, etc. As a result, there are  
some new pages that are not yet in your ToC. As I work, I'll apply the  
new 'manual' label to the pages and add them to the ToC where  
appropriate (if that's ok with you - if you'd rather edit the page  
yourself, let me know).

** One question for the group:

We decided to handle the API documentation (which must be tied to a  
release) by creating a snapshot copy of the relevant pages and  
renaming the copies to include the version number. So we will have a  
"Reorderer API v0.3" page (or some such naming scheme) in addition to  
the "Reorderer API" page. That, then, will be the 'official'  
documentation for that release, and if the API in the trunk changes,  
then people using the release still have a valid set of documentation.

The question is: How should the ToC handle this? Should it reference  
the versioned pages? The 'trunk' pages? Both?

(FYI the process of creating these versioned copies for this release  
will be happening later today).

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto