Mark Leicester wrote:
Hello,
I don't really want to define a global structure a priori because I
expect each documentation writer will have their own view of how
documentation should be organised. However, we will periodically need
to discuss and agree how to better organise what is already there
(refactoring if you like). For example, at CocoonInAction[1] there are
already some documents about getting started with Cocoon. I want to
add some information I've written in the wiki[2]. Here's my take on a
structure for what we already have:
Getting started with Cocoon
+ Installing the prerequisites
+ Java
+ Getting the latest release of Cocoon
+ Downloading a Cocoon release
+ Getting Cocoon from the source repository
+ Installing and configuring your IDE
+ Eclipse
+ Subclipse
+ Checking out Cocoon
+ Using the command line
+ Using Subclipse
Honestly, this section should IMO go into an "advanced topics" section,
as beginners really don't want to use the latest and greatest directly
from svn...
And my impression is that explaining this in the first pages of a
"getting started" is more frightening than useful :-)
+ Building and running Cocoon
+ From the command line
+ From within Eclipse
+ Configuring Cocoon
+ What's in cocoon.xconf?
+ ...
+ What's in web.xml?
+ ...
+ Logging
(drawing a little from Tony's proposal from 2003[3])
To aid document reorganisation I think we should encourage a fairly
fine-grained modularity, i.e. single topic pages.
Also, as we go about building documentation on CocoonInAction, what is
the best medium for these sort of discussions? Should we revive the
docs list? Or should we continue to use the dev list? What do you think?
Cheers,
Mark
[1] http://cocoon.zones.apache.org/daisy/cocooninaction/
[2] http://wiki.apache.org/cocoon/LoadInEclipse
[3] http://wiki.apache.org/cocoon/DocsReorgProposal
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
