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: <4201D3DD.7020105@apache.org>
Date: Thu, 03 Feb 2005 08:33:49 +0100
From: Reinhard Poetz <reinhard@apache.org>
User-Agent: Mozilla Thunderbird 0.9 (Windows/20041103)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [Bug 33334]  - [docs] 1st version of "Building your own Coco
 on project using Ant"
References: <329A68716B57D54E8D39FD3F8A4A84DFBF3F47@um-mail0136.unimaas.nl>
 <4200AD7B.9010405@upaya.co.uk>
In-Reply-To: <4200AD7B.9010405@upaya.co.uk>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

Upayavira wrote:
> H.vanderLinden@MI.unimaas.nl wrote:
> 
>> Some issues, that might involve the whole of the documentation:
>>
>> * As already stated by reinhard:
>>
>>
>>> one note: generally we have to discuss how we deal with the versioning
>>> problematic. If one documentation is talking about to many versions 
>>> at the
>>> same time, it can be very confusing.
> 
> 
>> I agree that too much version dependent documentation is bad, but in this
>> case the following needs to be resolved:
>> - does this still work for Cocoon 2.2? Can someone familiar with the new
>> things in 2.2 verify that this setup still works? If not, where are the
>> differences? I'd be happy to modify the content of the documentation if
>> someone tells me what to write.
> 
> 
> Really, the only way we're going to do this is to maintain (a) a 
> 'global' project documentation, and the rest of the documentation 
> alongside the relevant version of Cocoon. So, we'll have 2.1 
> documentation like we do now, and at some point we'll have 2.2 
> documentation as well. Documentation should relate to that specific 
> version.

with only some notes about things that have changed compared to the previous version

> Now, if we release 2.2.4, all we will have on our site is documentation 
> for 2.2.4 (under cocoon.apache.org/2.2/. If someone is using 2.2.2, they 
> will need to use the documentation that is included within the download. 
> That will be the way for people to find version specific information. 
> That is my understanding of the proposal.
> 
>> - I combined Ant1.5 and Ant1.6 info. For the general idea the version is
>> unimportant, but we might include that it only works for Ant 1.6 and 
>> up and
>> assume no one uses Ant1.5 any more.
> 
> 
> Just go for 1.6. AFAIK there is no reason why people can't upgrade, it 
> isn't exactly expensive!

agreed

> 
>> Maybe it is a good idea to include a section that specifically states
>> versions when relevant.
> 
> 
> For these sort of tutorials to be most helpful, they need to be as 
> simple as possible. And the way we achieve that is by telling the reader 
> what versions they _must_ use to benefit most from the tutorial. If we 
> wish, we could provide an appendix about how to use an alternative 
> version, but it should be an appendix and not break the flow of the main 
> document.
> 
>> * I included a list of TODOs at the bottom of the content. They 
>> concern the
>> content of the doc. They have to be done/decided on before this doc 
>> can be
>> marked as finished.
> 
> 
> I'll leave reviewing those to Reinhard!

I've put it for now into SVN. It was also a good testdrive for my custom 
pipelines :-)


>> * Do we go for US English or UK English?
> 
> 
> Now there's an interesting one. Of course it should be UK English. But 
> then I'm biased. Really, consistency is more important than anything - 
> the whole documentation having the feel of being one cohesive entity, 
> not a smorgasbord of collected items.
> 
>> * Can a native English speaker go over the content and remove any errors?
>> I'd be happy to correct them, as long as I'm told what to do.
> 
> 
> When Reinhard has reviewed it, I'll check it out. I'm sure it will be fine.

It's in SVN now

> 
>> * Before starting on the XPatchUsage (which is referred to in this 
>> doc): is
>> it still useful? I.e. is there a big change in 2.2 that makes this 
>> useless?
> 
> 
> Well, we can now include xconf snippets into our sitemaps, so maybe we 
> can work around some usage of xpatch. But there may be others (web.xml, 
> etc) where it is still required.
> 
> I also saw a doc someone posted on user list that looked like it could 
> make a useful brief "how to install" doc for Cocoon.

The document is fine for Cocoon 2.1 but before we can mark it as 
stable/finished, it has to use the new include features. About the xpatch, 
generally I agree with Upayavira but I would propose to have a project specific 
web.xml and simply copy it over the version that comes with Cocoon.

BTW, I plan to publish an Ant script, that supports the use of Cocoon 2.2 as 
base for a custom project. Helma, if you're interested in it, let me know!

-- 
Reinhard