Re: [RT] Moving towards a new documentation system

[Tony Collen <co...@umn.edu>]

Bertrand Delacretaz wrote:

<snip/>

> I'm starting to think (and I think this resonates with what Tony was 
> saying) that the physical structure of the docs should be flat, 
> wiki-style, having all docs "files" (real files or generated) in a 
> single directory, of very few directories like "reference", "documents" 
> and maybe "technotes".
> 
> We can then build all kinds of navigational structures, trails, multiple 
> tables of contents, beginners/advanced, whatever (again picking up on 
> wiki idea of a flat page structure with many navigation paths), but the 
> path to a given document stays valid forever unless documents are removed.

Yes, I agree.  The docs should all be in one place -- at least in the 
repository.  It will make things easier for us to find, and we won't 
neccesarily have the problem of trying to categorize new docs, or move 
existing docs into a more appropriate section.  More on this later...

> Of course we forfeit compatibility with our existing docs URLs, but I 
> think this is needed anyway to move forward.
> 
> This might also make our remodeling easier:
> 
> -move all existing docs to a small number of directories like above, 
> "big bag of docs"

Agreed.

> -rename docs as needed to give them permanent names

Also agreed.  I like the idea of giving the docs a permanent name.  This 
should be investigated thoroughly, though.  Remember that we can create 
whatever URL space we want, and have it totally decoupled from the 
physical layout of the docs in the repository.

> -create a very simple publishing system for now (Forrest probably?), 
> until the new docs system moves forward

> -start building the navigations, trails, tables of contents incrementally

Agreed.  The way I think of it, is if we have our so-called "big bag of 
docs", we can then create virtual categories, which are collections of 
docs in a specific order.  This will allow for any type of "virtual" 
docs layout -- be it trails, or straight up reference, TOC, index, etc.

The problem then would be tying in these virtual categories into the 
sitemap automatically somehow.

This way we could create trails, or references for just about anything. 
   (Does this duplicate any Forrest functionality?)

Here's how we could glue together a trail for the Flow:

<category name="teachMeFlowscriptTrail" title="Everything you need to 
know to use the Flow">
     <doc id="123-flow-intro.xml"/>
     <doc id="456-flow-basic.xml"/>
     <doc id="789-flow-advanced.xml"/>
     <doc id="012-flow-woody.xml"/>
     <doc id="345-flow-fom-ref.xml"/>
     <doc id="678-flow-jxt-ref.xml"/>
</category>

Likewise, we could glue together a reference for all of the generators:

<category name="generatorsReference" title="Generators Reference Page">
     <doc id="343-generator-intro.xml"/>
     <doc id="982-file-generator.xml"/>
     <doc id="356-html-generator.xml"/>
     <doc id="234-wsproxy-generator.xml"/>
     <!-- and so on, in order (alphabetical) -->
</category>

Obviously we'd want to abstract the actual filenames, preferably to get 
rid of the numbers out of the actual URL that it will be accessed 
through.  Then again, if we have a good naming convention, we might not 
need numbers on the files at all.

This could even let us keep the "old" urls for the fubared docs layout, 
all we'd have to do is create categories that reflect the current 
fubared layout ;)

Implementation is left as an exercise for the reader....

Regards,

Tony