Table of contents for Fluid user manual

[Paul Zablosky]

I have been giving some thought to Anastasia's points about "release 
specific manual pages".   My current feeling is that they be included in 
the ToC, along with the release-independent versions.  This gives the 
reader of the manual a comprehensive view of the material, some of which 
is general, and some of which refers to a particular release.  If the 
page naming scheme reflects the distinction, a glance at the ToC will 
inform the user which is which.

We can add an explanation of this to the README file, which , by the 
way, can be found in draft form at http://wiki.fluidproject.org/x/BQIs.

Those of course are just my thoughts from a distance.  Whether this kind 
of approach works will depend somewhat on just how much release-specific 
material there is.

Paul

Anastasia Cheetham wrote:
>
> 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).
>