cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira ...@odoko.co.uk>
Subject Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Date Fri, 03 Jun 2005 14:14:46 GMT
Mark Leicester wrote:
> Hi everyone,
> 
> Starting at the very beginning... I am reviewing the introduction on the 
> Cocoon home page: http://cocoon.apache.org/ (The "Apache Cocoon" 
> section). I've added mention of flow, templating and the forms 
> framework, and tried to increase the emphasis on Cocoon's suitability 
> for web applications (not just publishing). Possibly contentiously, I've 
> taken out the references to lego(TM) and glue. What do you think of:
> 
I've moved that bit to the end, because it seems to come second to me.

> My company will pay me to do another four weeks of full time work 
> reviewing Cocoon documentation (worth about £6000 I guess - a very good 
> place to start: that's the dough taken care of). My work will include:
> - Patches to existing documents.
> - Reorganisation of existing documents.
> - Revisions of wiki documents.
> - New documents.

Hey, anyone offering time, we'll appreciate it. Time is what the docs 
really need, for sure.

> In terms of semi-supported, semi-official documentation work I am aware 
> of Helma's efforts at http://cocoondev.org/handbook, Ray was 
> contributing something too, and obviously I am aware of the work 
> Sébastien and Me are doing at http://www.planetcocoon.com. At the moment 
> there seems only sporadic work on the wiki, see 
> http://wiki.apache.org/cocoon/RecentChanges. Who else is writing 
> content? Where? How shall we divide up the work?

There's also mine and Reinhard's effort to rework the existing docs in 
readiness for 2.2.

Some points:

  * Myself and Reinhard have been working on converting the docs to 2.2.
    We have got a decent framework in place, but we haven't done much
    work on actual documentation. Rerunning the 2.1 to 2.2 conversion
    process wouldn't be that hard.
  * If we want to get anything you do published quickly (i.e. less than
    six months), it is going to have to end up in the 2.1.X Cocoon SVN.
  * This will mean that the end result will be xdocs, not HTML. However,
    I don't believe converting HTML to xdocs would be hard, and I'd
    happily knock up a script to do any necessary conversions.
  * I'm not that fussed where a document is worked on before it gets in
    to SVN, so long as:
    (a) it is accessible to a wide range of people who can contribute
    (b) change notifications are sent out whenever content is changed
        (this is necessary to trigger an otherwise lazy community to
        take notice of your work)
    (c) it isn't too hard to convert the content across to HTML or xdoc
        format.

So, I'd say that the work that is required is to do sort out the 
reference documentation, and to extend that with tutorials and 
introductory material. What area would you want to be starting with?

> If you've followed me so Far, then I have another question. What is the 
> best way to have my work reviewed by the community? To test my 
> understanding of the current process: for each revision, I would do one 
> of the following: make a change in the wiki (are these actively 
> reviewed?); send a patch to bugzilla (it'll be a lot of patches; how do 
> I submit reorganisations?); or as with the above, start a discussion on 
> the dev list (I believe the docs list is for change notifications only?).

Patches is how content will need to get into SVN, but isn't, as you 
suggest, the best way to actually go about the editorial work.

> A less time consuming alternative for me would be to Sew it all together 
> at Planet Cocoon, as it is already set up with infrastructure for anyone 
> wishing to join in, tools for workflow, categorisation, document 
> hierarchy management etc. If I were to take that approach, then my work 
> would be continuously visible. Naturally, all my work will be donated 
> back to Cocoon. And then it'll be time for a nice cuppa. Which brings us 
> back to... What do others think?

Start small, do a page or two at a time, so you can stop at any point 
and there's something valuable left. And we can complain and say "no, 
that's not what we want" before you've wasted heaps of time.

Other than that, just get on with it :-)

> P.S. this took nearly all morning to write. D'oh!

I can believe it!

 > +----------------------------------------------------+
 > What is Apache Cocoon?
 >
 > Apache Cocoon is an MVC web application framework uniquely suited to XML
 > publishing.
 >
 > Apache Cocoon is founded on the principle of separation of concerns.
 > Cocoon's Avalon-based component architecture makes it easy to create web
 > applications from reusable components. You use the Cocoon Sitemap to
 > assemble components into pipelines. Pipelines react to client requests,
 > generating information from a source, transforming it, before
 > serializing it back to the client in the desired format. This separation
 > of concerns between generation, transformation and serialization, allows
 > the same source to be served up to your browser, cellular phone or
 > printer, or to be consumed by your web service.
 >
 > In addition to this mature publishing framework, Apache Cocoon offers
 > features and frameworks to help you build full-featured web
 > applications. Cocoon Flow offers continuation-based scripting for your
 > application business logic. Cocoon Templates offer dynamic XML
 > generation. The Cocoon Forms framework greatly simplifies client
 > interaction with a growing library of user interface widgets for your
 > web application forms.
 > +----------------------------------------------------+
 > I've embedded links to wikipedia definitions for MVC and SoC, visible at
 > http://www.planetcocoon.com/node/2155.

To be honest, I'd probably leave this bit until a little later. This is 
probably one of the more contentious pieces. Start somewhere simpler! I 
can imagine a very long thread about a short, pithy, summary of what 
Cocoon is, and I think we would do well to leave that for a week or two. 
Does that sound reasonable?

Look forward to seeing what you come up with.

Regards, Upayavira

Mime
View raw message