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
