cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Giving up! Cocoon too big, slow and confusing
Date Fri, 28 Jun 2002 13:45:07 GMT

On Friday, June 28, 2002, at 07:46  AM, Derek Hohls wrote:

> only the way that it is *perceived* - as a suggestion; can
> anyone point to concrete examples of complex, but well-
> documented, easy-to-learn open-source projects =>
> lets adopt their approach(es) and see where/how we
> can change what we have (or add where there are gaps)
> to get to a better place.

For those of you who may not follow cocoon-dev or updates to the cvs, 
here's a bit of history about what's happened recently with the Cocoon 
doc effort.

Well when I first started working on Cocoon docs, in late April, I 
visited a lot of web sites. IMHO, some of the successful open source 
doc-oriented sites are:
   LinuxDocs http://www.tldp.org/
   Zope Docs  http://www.zope.org/DocProjects/
   PHP Docs  http://www.php.net/manual/en/

I did a quick analysis of the state of Cocoon docs, and posted a 
questionnaire to gather feedback from other developers/committers on 
cocoon-dev. In hindsight, I should have posted it here as well. Sorry 
about that, but I'm learning too. If anyone would like to provide input 
to that questionnaire, please do so by reading this thread:
   http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101924654819206&w=2

Since there were a number of Cocoon books scheduled for release soon, I 
decided *not* to start by improving the core docs (although I have 
started some ad-hoc editing and revisions. Rather, I decided instead to 
focus on facilitating community contributions. Thus, my first priority 
was to expand the pool of authors. I figured the best way to "start" was 
to solicit contributions of most granular form -- FAQs, Snippets, and 
How-Tos. If you do a search of "howto" at 
http://www.zope.org/DocProjects/, you will find 589 How-To articles!! 
Therefore, I wrote guidelines on how to contribute FAQs, How-Tos, and 
Snippets and provided a few examples of my own. I didn't try to reinvent 
the wheel. These guidelines were based on existing guidelines in use 
around the web. If anyone has suggestions about how these guidelines 
could be improved, please let me know.

I then refactored the FAQs into separate pages to make them more 
accessible and more maintainable by our current patch update process. My 
hope was that some users would start to patch FAQs -- taking on a whole 
topic of FAQs even. That has happened already. For example, just 
yesterday, Luca Morandini contributed a patch with substantial changes 
to the Configure Environment FAQ. You may want to check it out in HEAD 
and 2.0.3 release branches. When I have time, I too try to harvest the 
many FAQs gems on this list. But I don't have time to do everything. 
Unfortunately, there's remains a lot of great stuff on this list that 
really needs to go into an FAQ. Volunteers? Look, if you need to make 
sure you've expressed it properly, post a FAQ draft to this list. That's 
what I do. And I'm *really* grateful to all cocoon-user subscribers who 
take the time to respond to my draft FAQs.

Soon after the document guidelines were in place, David Crossley wrote 
two excellent How-Tos: How to Prepare a Patch (any contribution, whether 
based new or revised content, is considered a patch by Bugzilla) and How 
to Contribute a Patch via Bugzilla (how patches get processed by 
committers into cvs). Then it was simply a matter of letting users know 
that they could contribute. We've already received two docs, the XML 
Form How-To, written by Heidi-Marie Brannan, and a Generator Tutorial, 
written by Carolien Coenen and Erwin Hermans. Also, Konstantin Piroumian 
contributed a How-To for committers, (at Forrest), CVS through SSH, 
using these same guidelines. Feedback received through these initial 
authoring efforts has been incorporated into the document authoring 
guidelines. I just finished a new How-To on the Paginator Transformer, 
based on content originally authored by Stefano Mazzocchi. However, as 
of yesterday, we were still working out a few issues with the associated 
samples. Thus, it's not in the release branch or on the live site *yet*.

As for the core docs, improvements (at least from me) are going to have 
to wait until Cocoon makes its transition to Forrest and the updated 
document.dtd. A number of Cocoon committers are also active with the 
Forrest project. That process is definitely underway but it's a lot of 
work. Once the new doc architecture is in place, the first thing I'll 
consider doing is refactoring and expanding existing docs based on 
Gerhard Froehlich's proposed outline. Check it out at: (warning: long 
link, may break on some email clients...)
http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-
cocoon2/src/documentation/xdocs/drafts/newtoc.txt?rev=1.1

Even if you don't have time to write anything, any comments/additions on 
the proposed outline are more than welcome.

Please also understand that the Cocoon documentation is deployed on a 
static web site. Until that changes, a number of other documentation 
gathering/updating approaches simply aren't possible. However, if you 
have the interest, you can contribute to a Cocoon-based wiki at
    http://www.anyware-tech.com/wikiland/

It is hoped that input from that wiki will be rolled into core Cocoon 
docs.

Users can make a significant difference with docs. I honestly believe 
Cocoon is trying to implement approaches based on other successful 
documentation projects. Your suggestions for additional approaches are 
welcome. But none of this will work without new blood.

-- Diana


---------------------------------------------------------------------
Please check that your question  has not already been answered in the
FAQ before posting.     <http://xml.apache.org/cocoon/faq/index.html>

To unsubscribe, e-mail:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>


Mime
View raw message