cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira ...@upaya.co.uk>
Subject Re: [RT] doco lite?
Date Tue, 26 Oct 2004 20:32:12 GMT
Jorg Heymans wrote:

>
>
> Bertrand Delacretaz wrote:
>
>>
>> GOALS
>> G1. Generate our docs and website dynamically, directly from the SVN 
>> repository accessed over http
>> G2. Give access to older versions of the docs using standard SVN 
>> mechanisms (tags etc)
>> G3. Index the latest version of the docs, including structured fields 
>> (keywords, target audience, components mentioned, etc), to implement 
>> "prepared queries" (as links, simply) to improve our docs' accessibility
>>
>> TOOLS / TECHNIQUES
>> T1. Get content from SVN, editing is considered a separate problem
>>
>> T2. Build an index with Lucene, triggered via SVN post-commit hooks, 
>> uses a live Cocoon instance to generate an easy to index XML document 
>> for Lucene. Include metadata fields as mentioned in G2 above, 
>> generated from (enhanced as compared to now) document content
>>
>> T3. Generate pages using a live Cocoon instance, maybe Forrest. SVN 
>> tags "pass through" the URLs to give access to older releases of the 
>> docs.
>>
>> T4. Use queries like "find all documents which talk about sitemap 
>> matchers" to build navigation pages semi-automatically.
>>
>> T5. Put mod_cache in front to minimize server load (HTTP POST can be 
>> used to invalidate pages if quick updates are needed to check edits).
>>
>> WDYT?
>
>
> I pondered long (well, about 5 minutes) and hard on how to correctly 
> phrase the first two things that came to my mind when I read your 
> proposal - so here goes :
>
> 1)Does all this actually make the documentation any better?
> 2)Should any effort towards documentation ATM go into improving its 
> *quality* or improving its 
> {searchability|updateability|scaleability|auto-generateability}

As we discussed at the hackathon, I think both are concerns that 
interrelate, and effort can be applied separately to either.

As it is, we have a complex system that few people know how to operate. 
I've written docs, but I've never deployed them to the site. This acts 
as a dis-incentive to existing and potential documentation writers.

Other than that, we have a xdocs system that does work, and a wiki that 
works. We can use right now to write better docs. We just need to make 
the effort.

So I think both are valid - documentation quality and publication tools.

Regards, Upayavira


Mime
View raw message