cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
Date Sat, 11 Oct 2003 12:11:14 GMT

On Saturday, Oct 11, 2003, at 11:36 Europe/Rome, Bertrand Delacretaz 
wrote:

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

eheh, seems like the memes start to percolate. good.

I think the documents should have a *numerical* identifier that equates 
them with a URI.

  http://cocoon.apache.org/cocoon/LO/3948494

where "LO" stands for "learning object".

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

Exactly. Right on.

With a numberical identifier, we can even keep the page if we change 
its title (this will ease refactoring and reduce the chance of future 
migration... btw, this is the approach used by DOI and DSpace... note 
that this is exactly the same concept I use for linotype, where news 
are identified by a unique incremental number)

> Of course we forfeit compatibility with our existing docs URLs, but I 
> think this is needed anyway to move forward.

Big +1, we have to cut the rope at some point.

> This might also make our remodeling easier:
>
> -move all existing docs to a small number of directories like above, 
> "big bag of docs"

+1

> -rename docs as needed to give them permanent names

yep

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

a first step could be the introduction of files that contain navigation 
structure. They could also be xslt processed to generate .htdocs file 
for mod_rewrite instructions so that we don't expose those URI directly 
but we wrap them with nicer-looking addresses.

[it's the static equivalent of a lookup]

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

yes, the links can be refactored without

> -if the docs format changes for the new doc management system, 
> navigation definitions stay valid

true and in the future, we can still use those to seed a more dynamic 
approach.

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

big +1

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

-1 for acronyms.

--
Stefano.


Mime
View raw message