cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: [vote] cocoon-docs
Date Thu, 09 May 2002 12:30:17 GMT
Diana Shannon wrote:

> >  How will that differ from the dev list?
> The dev list is about developing first-rate software. Stefano argues
> passionately that software design solutions should not being driven by
> implementation difficulties. Right now, cocoon docs suffer because they
> are not "implemented" in response to a well-articulated design goal
> based on "real world" needs of users. If you developers only knew just
> how *hard* it is to use Cocoon with the existing document set. Just
> yesterday, I was pulling my hair out, working on a sitemap from scratch,
> trying to remember the exact configuration detail of a specific pipeline
> component I needed. I had to dig through five different pages to find
> the information I needed. It's just too frustrating, even for a
> motivated user.

Oh, I exactly know how hard this is, but the difference is that we *DO*
have great docs for Cocoon: the code itself. :)

I have to admit that normally I don't even touch the Cocoon
documentation (not even javadocs) and go straight to the source files...
this community is probably formed by people who are all able/willing to
do that. The user community is formed by people who don't want to do it.

And I'm totally with Diana that we should make life easier for those who
don't want to follow our development mode. So I'll make an effort *not*
to touch the source code but to try to start from the docs.

I suggest all of you to do the same and I'm pretty sure much more
documentation itches will emerge for you to scratch.

> A doc-list will be better able to direct document development effort
> because it will be the product of more concerns. I'm not talking only
> about authors and editors but also trainers, educators, publishing
> folks, content experts -- all of them Cocoon users! I know many
> developers care about documentation, but limiting the discussion to a
> list that is dominated by development concerns isn't "healthy." To
> extend the recent RT evolution analogy, I'm trying to increase the
> diversity of the contributing gene pool, not wait for developers to
> genetically sprout documentation expertise. Remember, evolution of a
> species occurs over huge time frames (relative to  individual
> lifetimes). We have a diverse community of users we haven't begun to
> engage in the process. They need a place where they can express their
> views, without being accused of making "stupid" posts. A doc-list will
> provide a more balanced points of view, and it won't be perceived as a
> second-class citizen. It will articulate holistic design goals for docs,
> and work out effective implementation details. I think it will also help
> to simplify the submission/review process.

I'm willing to try this approach. I do believe it's entirely possible
that very few people will subscribe there and many developers will
continue to follow their habits, but community dynamics (like evolution)
are extremely hard to forecast (due to their intrinsic non-linear

Since what we have today doesn't work, I think we should do something
different and what Diana proposes might not be a perfect solution but
it's definately a new step and I trust her judgement on that.

> > If everyone on dev should read doc, too, and I assume people on the
> > doc list should monitor dev as well, as ideas are discussed and
> > announced (sometimes even explained ;-) on the dev list. What
> > difference would it make?
> I don't agree that all doc list subscribers will want to (or should have
> to) monitor the dev list. 

Yes, and the opposite, but I think that we should try to give the
ability for each person to focus on what they care. SoC at the community

> Some are going to pop in and out for very
> brief periods of time, for input on documentation they are authoring,
> period. Look, documentation folks are a different breed of people. We
> care as much about elegant, effective prose as you do about elegant,
> effective code. We get the biggest thrill, seeing the "light turn on" in
> the eyes of a struggling learner/reader. You need *both* efforts to
> sustain Cocoon's growth at this point in time, and you need to address
> both needs equally with separate lists. IMHO the quality of documents is
> holding back Cocoon's growth. I take *great* issue with the notion that
> incremental development is inherently sustainable. Sustainable growth is
> a result of *not* outstripping your resource base, in this case, users
> and developers alike. A major negative feedback loop kicks in when
> user's can't keep up with the pace of change -- however incremental --
> particularly when documentation is poor. Just because change is
> incremental, the result of many small efforts, doesn't mean the
> resulting "impact" is small. Think about population growth problems.
> Lots of people incrementally adding one child at a time can easily
> create a major sustainability problem.
> > What about using Wiki pages for documentation?
> One of my medium priorities on todo-doc.xml is to explore wiki for QA
> and maintenance purposes.  I *still* believe you need a more centered,
> somewhat structured effort to create enough "meat" to help even wiki
> efforts succeed. 

Agreed. Look at the PHP docs (which are very nicely done, IMO): they do
have user comments at the end of their pages, but the do have structured
and edited pages first.

> I think there's a tendency to throw technological fixes
> at every problem. 

Ah, gosh, I revote +1 on the cocoon-docs list (and to your commit
access) just for this single sentence right here.

And now, excuse me, but I have to kick some asses.

Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<>                             Friedrich Nietzsche

To unsubscribe, e-mail:
For additional commands, email:

View raw message