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.
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!
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!
* 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.
* 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.
Regards, Upayavira
