I did some "documentation port" myself, but I have to admit it is
not that easy, since something *may* indeed have changed in the
passage... bottom line: you have to know a component's behaviour in
both 2.1 and 2.2 before safely porting its doc.
You're so right about that. It is a big job.
I started updating the HTMLSerializer [1] but then realized there
were actually two implementations of it with different sets of
parameters. Not only that but a lot of 'folklore' and list wisdom
was trapped in the mailing list and on the old wiki over the last
few years and that needed to be set free.
I hope it is OK if I jump into this discussion - during the recent
months I have been working with Cocoon 2.2 a lot - it is really hard
to find documentation about some of the "advanced" features - and it
is even harder if some information are simply wrong (because they are
not up to date). I know I have not done my duty and corrected these
errors :-(
During some spare minutes (running, driving) I thought about about
possible ways to improve the documentation. On some blogs ([1], [2]) I
have found a lot of interesting (and quite accurate) information which
I could not find on the official cocoon page. I liked the HOWTO-
approach which imho is missing for many features (e.g. ("HOWTO
configure authentication")). The bits and pieces are there and
documented but I often miss the "red line" (hope I can say that in
english).
As there is no official cocoon blog as far as I know I think such a
blog would be a good way (in addition to the existing documentation) to
a) publish HOWTOs that do not fit into the source documentation
b) publish articles that aggregate information from the existing
documentation/link to them
c) link to other interesting articles from outside (which might
motivate some people to write about cocoon to get some traffic from
the official blog)
d) inform about updates
e) inform of other cocoon/apache-related events
What is published there could be revised by some developers before
publishing and people from outside can easily contribute stuff.
Commenting would also allow to improve possible published best
practices… Tagging would allow to structure information…
Just my two cents - thanks for reading this,
Benjamin
[1] http://mrhaki.blogspot.com/search/label/Cocoon
[2] http://happygiraffe.net/blog/tag/cocoon/
