cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ivelin Ivanov" <>
Subject Re: [vote] cocoon-docs
Date Fri, 10 May 2002 01:15:23 GMT

The discussion on where the DOCS should be discussed is burning a lot of
energy which could be used to build the DOCS.

Yes, newbie friendly documentation is a must for Cocoon's survival. I am
also having difficulties helping people get up to speed on simple problems,
because I can't quickly refer them to a rich documentation source.

Dianna, can you please start a separate thread and begin to build the
documentation itself.

Is there a easy way to create a docs list and have a server side robot
automatically prepend [DOCS] to the subject and forward each message to the
users and dev list?

I am +1 if this is doable.



----- Original Message -----
From: "Stefano Mazzocchi" <>
To: <>
Sent: Thursday, May 09, 2002 7:30 AM
Subject: Re: [vote] cocoon-docs

> 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
> nature).
> 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
> level.
> > 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:

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

View raw message