cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <bdelacre...@apache.org>
Subject [RT] Moving towards a new documentation system (was: [RT] Updating the website)
Date Sat, 11 Oct 2003 09:36:08 GMT
Le Samedi, 11 oct 2003, à 04:21 Europe/Zurich, David Crossley a écrit :

> Tony Collen wrote:
>> ...We might need to get away from the "developer" vs "user" notion, 
>> because depending on how much about
>> Cocoon you already know, you might have to hack out a new generator 
>> (which would seem to imply
>> information in the developer section) while you are really a user.
>
> +1 ... we have talked about that many times. Almost every
> user is a developer. Anyway "Trails" are better navigation method.

+1

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.

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
-start building the navigations, trails, tables of contents 
incrementally
-if the docs format changes for the new doc management system, 
navigation definitions stay valid

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.

Thoughts?

-Bertrand


P.S. We need to find a name for this new doc management system - I'm 
low on ideas noew but maybe CDMS? Cocoon Documentation Management 
System?


Mime
View raw message