Hi Reinhard, Helma and others,
A big thanks (again!) for your work on the documentation.
With my sceptical hat on, I took a quick glimpse at
http://cocoon.zones.apache.org/dev-docs/, and found myself actually pretty
surprised by the refreshing new look. :)
But I hope you don't mind if I add some (really trivial) suggestions..
I'm not going to dive into the quality of the content itself, since this is
clearly a work in progress. But there's some small things about the structure.
News on the homepage: excellent!! I love it. It would be better
if we could have the date presented as part of the title:
# 10/18/06: News Management in our Docs
<small>submitted by Ross Gardler, 10/18/06 9:59:32 PM</small>
We are experimenting with a news management system in our
Daisy driven documentation system. Simply create a new
document with the type "NewsEntry" <snip> ... [more]
# 10/17/06: Cocoon GT 2006 in Amsterdam
<small>submitted by Reinhard, 10/17/06 9:59:32 PM</small>
The Apache Cocoon community is proud to announce the fifth (!)
annual edition of the Cocoon GetTogether, the main annual
... [more]
The 4 hour update schedule is more than enough for me.
Still, I'd love to see some blogentries right there on the homepage as well...
Just an aggregate of committer blogs that list only items categorized as
'Cocoon'.
> - Following the split up of Cocoon (the code) we also split up the
> documentation into much smaller pieces. The rule is that
> each deployment
> unit has it's own documentation.
Although this is fine with me, I got lost in the subsite-principle. I'd much
rather have a single navigational structure for all parts. It took me a while
before I noticed "Cocoon core" in the top navigation, clicked on it and got to
something that looks like the same website, but has a completely different
navigation. Maybe I've missed out on this discussion, but it makes it really
hard for me to find things.... What is the reason for this?
> - The documentation is automatically exported to
> http://cocoon.zones.apache.org/dev-docs/ every 4 hours.
I noticed that this website is horribly slow... Got any clue why this happens?
> At http://cocoon.zones.apache.org/daisy/cdocs/1201.html you
> can find how-tos (about adding and publishing docs) and an
> overview of how the documentation system works.
I guess the editing part should mimic the presentation from the published
result?
> Helma will also work on a new flashy design for our site,
> though we both don't think that this effort should block
> publishing the docs using the "well-known"
> Maven skin as soon as the content is good enough. Does
> anybody disagree?
I totally agree! Let's get things rolling first..
On a sidenote, if someone has a drawing of the Cocoon 2.1/2.2/3.0 architectures
(sketch would be fine), I could get it redone by the guy who is currently
redesigning Hippo's architectural diagrams. Same goes for the 'pipelined
transformation' graphic. Could explain a lot if we would have that on the
homepage!
> As many people agreed that it is *very important* to have
> good documentation, Helma and I hope that others join us.
> Don't hesitate if you think that all this stuff is
> complicated. It's definitly not! Just go to
> http://cocoon.zones.apache.org/daisy/, choose the site that
> you want to improve and do it!
Now, is there anything we can do about the Wiki pages? There have always been
quite a bunch of pages that on the Wiki that deserve to be moved into the
documentation.
Also, the Wiki used to have a very low entry barrier, it would be easier to use
that as a sandbox and move finished docs into the documentation website.
Thanks for picking this up!
Arjé
