Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Date: Wed, 8 May 2002 12:52:38 -0400
Subject: Re: [vote] cocoon-docs
Content-Type: text/plain; charset=US-ASCII; format=flowed
Mime-Version: 1.0 (Apple Message framework v472)
From: Diana Shannon <terracare@mac.com>
To: cocoon-dev@xml.apache.org
Content-Transfer-Encoding: 7bit
In-Reply-To: <20020508092914.O27312@bremen.dvs1.informatik.tu-darmstadt.de>
Message-Id: <00EE4C52-62A4-11D6-8126-0030653FE818@mac.com>

Christian:

> On 06.May.2002 -- 08:03 AM, Diana Shannon wrote:
>> I think a separate list will accelerate the documentation effort,
>> particularly in the planning stages. I also think it will provide a 
>> more
>> inviting, less formal way for authors to get feedback on their
>> contributions.
>
> Diana,
>
> what discussions / questions would you like to see on the doc list? We
> will need a guideline for this.

IMHO, anything related to creating first-rate documentation which, in 
turn, helps people learn/adopt/use Cocoon more effectively will be OT.

A *few* of these discussion topics are included on the todo-doc.xml I 
committed yesterday. My cvs message hasn't shown up on the list yet 
(subject to moderator approval), so perhaps you missed it. There will be 
more topics, inevitably, but I that's all I have the energy to 
articulate right now.

>  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.

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.

> 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. 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. I think there's a tendency to throw technological fixes 
at every problem. I'm not sure wiki is appropriate for *all* kinds of 
docs. I still think we need to meet minimum requirements with a base 
documentation set distributed with Cocoon. Not everyone will use wiki. 
Still, we can gather useful feedback from wiki and other QA mechanisms. 
I'm open. I'm not a wiki expert. I *want* the effort to explore it.

> What if we had put all this effort discussing a new list into writing
> docs? ;-)

Any interested person can check out todo-doc.xml. Many of the items 
listed there are a result of what were helpful discussions, at least for 
me. I also think you're overstating the "effort" extended towards these 
kinds of discussions. For some, especially the *new* contributers I hope 
to bring in to the process, talking about something is the first step 
down the road towards contributing something tangible. Dampening these 
very preliminary discussions is counter-productive. As for my own 
efforts, I wanted to gather some input before diving into the cvs to 
start "fixing" the docs. In a complex system, that's called "shifting 
the burden." It does *nothing* to solve the underlying problem.

Diana


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