cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Haul <h...@dvs1.informatik.tu-darmstadt.de>
Subject Re: [vote] cocoon-docs
Date Wed, 08 May 2002 18:17:53 GMT
On 08.May.2002 -- 12:52 PM, Diana Shannon wrote:
> >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.

u-huh, thought OT to mean "off topic" ;-)

> 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?
<snip> We all agree that we need better docs</snip>

> developers care about documentation, but limiting the discussion to a 
> list that is dominated by development concerns isn't "healthy." To 

I don't understand this.

> 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 

So far, I have seen little to no such accusations. Esp. the Vadim-bot ;-)
is very patient with answering the same question over and over again.

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

Sure, technology is no solution for a social problem. It's just that
wiki lowers the entrance barrier for interested persons to join the
documentation effort. Find an error and correct it. See an aspect missing,
open a new page and write a paragraph. Someone else will fill in the
rest. Granted, a well planned document will seldomly result from that.

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

So does a new list. 

Anyway, I change my -1 to a +0. There's probably little harm in creating
a new list. The greatest positive effect most certainly is that someone
really cares about the docs and kic^D^D^Dmotivates the community to work
on the docs. The great vote you recieved shows that we really appreciate
your committment.

	Chris.

-- 
C h r i s t i a n       H a u l
haul@informatik.tu-darmstadt.de
    fingerprint: 99B0 1D9D 7919 644A 4837  7D73 FEF9 6856 335A 9E08

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


Mime
View raw message