cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: The Cocoon documentation: a lot has happened here
Date Mon, 06 Nov 2006 17:21:33 GMT
Arje Cahn wrote:
> 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]

should be possible, will have a look at it.

> 
> The 4 hour update schedule is more than enough for me.

note that we can only automatize it completly for the preview version that is 
deployed to cocoon.zones.apache.org. For cocoon.apache.org we still have to 
check in our docs into SVN which requires a handful of manual steps.

> 
> 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'.

TBH, I don't have a good idea how to integrate this ... :-/

> 
>>   - 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?

IMHO the documentation for a deployment unit should be able to stand alone. For 
me it's more confusing if a get a tree with hundreds of nodes.

One of the goals of the new design should be a clear navigation that makes it 
obvious where to find what.

>>   - 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?

Currently it's pretty fast, but we don't have a guaranteed performance at the 
zones server.

> 
>> 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?

What do you mean with "editing part"?

> 
>> 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!

that would be great!

>> 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.

yes, using Daisy as our wiki would be great but it needs somebody who drives 
this effort

> 
> Thanks for picking this up!

-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------

		
___________________________________________________________ 
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de

Mime
View raw message