Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Message-ID: <417EB44C.7060402@upaya.co.uk>
Date: Tue, 26 Oct 2004 21:32:12 +0100
From: Upayavira <uv@upaya.co.uk>
User-Agent: Mozilla Thunderbird 0.7 (Windows/20040616)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [RT] doco lite?
References: <5DBE1B70-277F-11D9-8DE4-000A95AF004E@apache.org>
 <clma5n$bqn$1@sea.gmane.org>
In-Reply-To: <clma5n$bqn$1@sea.gmane.org>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

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