cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Arje Cahn" <a.c...@hippo.nl>
Subject RE: The Cocoon documentation: a lot has happened here
Date Mon, 06 Nov 2006 15:29:49 GMT
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é

Mime
View raw message