Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Message-ID: <012401c1f7c0$29567d00$0c91fea9@galina>
From: "Ivelin Ivanov" <ivelin@apache.org>
To: <cocoon-dev@xml.apache.org>
References: <00EE4C52-62A4-11D6-8126-0030653FE818@mac.com>
 <3CDA6BD9.EBBFA7F7@apache.org>
Subject: Re: [vote] cocoon-docs
Date: Thu, 9 May 2002 20:15:23 -0500
MIME-Version: 1.0
Content-Type: text/plain;
	charset="ISO-8859-1"
Content-Transfer-Encoding: 7bit


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.


Cheers,

Ivelin


----- Original Message -----
From: "Stefano Mazzocchi" <stefano@apache.org>
To: <cocoon-dev@xml.apache.org>
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.
> <stefano@apache.org>                             Friedrich Nietzsche
> --------------------------------------------------------------------
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org