cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: [RT] Moving towards a new documentation system
Date Sat, 11 Oct 2003 12:25:10 GMT
Bertrand Delacretaz wrote:
> 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".

Agreed. Forrest also has a wiki format and can use semantical html. 
Using HTML has also the benefit of making the docs easily viewable off 
from CVS.

> 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.

Forrest's site.xml is ready to adapt to the needs.

> 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"
> -rename docs as needed to give them permanent names
> -create a very simple publishing system for now (Forrest probably?), 
> until the new docs system moves forward

Eh, why "Forrest /probably/ "?

> -start building the navigations, trails, tables of contents incrementally
> -if the docs format changes for the new doc management system, 
> navigation definitions stay valid.

There was a discussion on Forrest about making all links be done to 
files without extensions, and now we use site.xml to reference these links.

The only thing that is still lacking is making the output remain 
"static" over time.

What I wanted to do is to have Forrest generate an index of pages and 
the users add this to CVS. With this index we have all the doc history, 
and Forrest can generate redirects if urls change. I also want want to 
generate redirects for filenames without urls and add an unique id to 
every page in the index, so that Forrest can add barcodes to the pages.

> I think we need to find a way to get started with this docs remodeling 
> without having to wait  too long on our improved doc management system - 
> if an incremental path like above works it might help us get started.

Please don't forget Forrest.

Nicola Ken Barozzi         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message