cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <>
Subject Re: "Apache Cocoon in Action" suggestion and call for opinions
Date Wed, 13 Apr 2005 05:58:07 GMT
Sebastien Arbogast wrote:

> Moreover this documentation could be written and reviewed in parallel
> and tight collaboration with the new Cocoon 2.2 documentation effort
> to make sure that the information is accurate and exact and to keep
> stuff in sync. And it could be written and reviewed/corrected
> progressively with the help of users giving feedback about what's
> missing and what should be removed.
> What do you think ? 

Why in parallel? Look at This 
build already contains an improved structure that is similar to yours that 
reflects Cocoon 2.2 in a better way than the current 2.1 docs do (although 
Upayavira and I discussed this for hours, this doesn't mean that it is carved in 

Writing docs for the new documentation system has become as easy as 
offline-editing can be:

     * Download, install and test [WWW] Forrest V0.6. It's a fairly big download,
       but easy to install.
     * From the src/documentation directory of your local copy of the Cocoon 2.2
       code, start forrest run. Note that Run, Forrest, Run! won't work.
     * Point your browser to [WWW] http://localhost:8888, you should see the
       Cocoon documentation page with the standard Forrest look (similar to the
       [WWW] 2.1 website).
     * After editing a document under the src/documentation/src/content/xdocs
       directory, refresh the page in your browser to see the changes


Every page is an HTML page which makes it very easy to write docs using your 
favorite HTML editor, no need for clumsy XML editors any more!

> Would anyone be interested in helping me to write such a documentation ? 

Upayavira, Bertrand and I have already started!

> Do you have ideas about technical infrastructure we could use : wiki,
> mail lists, maybe forums and IRC channel which are ideal for user
> feedback and easy communication, documentation format (forrest, SVN
> repository, writing and reviewing process) ?

the new documentation system based on Forrest and plain HTML docs

> What about work team organization (I find this very important to avoid
> stepping over each other's feet and make sure everything is correct
> and precise, even if it's longer) ?

if you have something to review, open a Bugzilla issue, use the prefix 
[documentation] for the subject and we can work on it.

> What about translations : would some people interested in translating
> that documentation to other languages as we write it (french ? spanish
> ?) maybe a few polls on local development communities would be
> necessary to determine what languages are worth translating to.

the new documentation system also covers this to a certain degree (the docs do 
but the structure doesn't --> I'm waiting here that future Forrest versions 
cover multi-language support) but for now we should concentrate on English

> What about a common website area to centralize efforts and make the
> project known to users and potential writers ?

for now this is

> Maybe it's not necessary to talk about the content in the first place,
> to insist on whether or not it would be interesting and if some people
> are willing to participate, and what could be the general shape of
> such a project...
> I'm waiting for your opinions. 
> FTR, I should precise that right now I'm working on a big project
> using Cocoon as its core XML server and it's my first project using
> Cocoon, which implies that
> -> I won't be able to spend my whole days on this

if others could spend their whole days on writing docs we would be finished for 
a long time ;-) anyway, you learn most if you regularly work with Cocoon

> -> I don't have much knowledge about Cocoon
> which means that even if I intend to use my newbie aspect to make the
> documentation accessible and my great interest in Cocoon to make this
> documentation successful, we would need many interested
> diverse-skilled people to bring this to realty in a reasonable time
> (that is before Cocoon 4 at least ;o)

I hope we can welcome you to the new documentation effort started by Upayavira, 
Bertrand, David and me - I think we already made some big steps forward

  - flat doc structure
  - multi-Forrest-repo customizing (we have to support many doc repos in the
    future as blocks will become intepend from Cocoon core and so their docs!)
  - optimized for an online-editor
  - old docs will be integrated within the next days
  - although this isn't that visible as dozens of already written docs.

For me it is important that we do all our work on a future-proof, easy to use 
and extensible fundament (see the above points). By the end of the week we are 
finished with this base work for the first and can move on to the "actual" work 
of writing.

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

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


View raw message