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). > _______________________________________________ fluid-work mailing list [email protected] http://fluidproject.org/mailman/listinfo/fluid-work
