cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject Re: Document Gestation Process?
Date Tue, 30 Apr 2002 13:55:11 GMT
On Tuesday, April 30, 2002, Andrew Savory wrote:

>> Right, but shouldn't they at least alert Cocoon about their efforts? 
>> Why
>> run the risk of duplicate effort when we have so many holes?
>
> Sure ... quite often in the past this happens with people sending an 
> email
> to the list saying something like "would anyone be interested in 
> <foo/>?"
> They'll then either be bombarded with "yes please" or "merge with X" or
> "here's my version, please add to it". I agree that holes in the content
> is a problem, but having a list of holes to fix (or even blank templates
> for people to fill out) will solve that.

You're right. In fact, some duplication is ok. I benefit when I read the 
two different authors explain the same concept -- differently.

>> But what if the author is overlooking something?  Wouldn't you rather
>> catch this in an outline than in a draft? Why are you adding extra work
>> for SMEs to fill in the missing content? Isn't it the authors job? I
>> don't want to make any extra work for SMEs who are probably busy enough
>> just contributing code!
>
> No, I wouldn't expect the SMEs to fill in the missing content - at most
> I'd expect them to say "you should include X". It's then up to the
> original author (or the community) to tighten up the document until it's
> complete. Two bonuses with this approach: it makes the original author
> more responsible for their work, and it teaches the author by showing 
> them
> gaps in their knowledge (making them better authors for the future).

I agree this feedback is helpful for the author. I'm just afraid 
informal QA isn't going high on anyone's priority list. Isn't that the 
case right now? Of course, I could be completely wrong. I haven't had 
time yet to study cvs patterns of documentation updates. A lot of my 
impressions of the "documentation problem" were formed when I was 
learning Cocoon2 last year. I gave up using the docs and resorted to 
learning by looking at the source. I am probably greatly underestimating 
the effort directed improving the docs since then. My apologies, if that 
is the case.

Diana


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


Mime
View raw message