[Zope] Re: Zope Documentation Plan

Darcy Clark darcyc@engin.umich.edu
Fri, 25 Feb 2000 14:03:20 -0500


I agree that authors of products shouldn't be mandated to provide
extensive docs....but I think that some of them could use a guideline or
a template to make the job easier *if* they wish to write docs for their
products. I didn't mean to suggest that this would a mandatory or
standardized thing....that just wouldn't work.

cheers,

Darcy

rgines@purina.com wrote:
> 
> >Re: Zope Documentation Plan :  two words......great news !!
> 
> >A minor suggestion .... docs for contributed products...having used many
> >of the user-contributed products, I have encountered variable quality of
> >docs (i.e. "ranging from here it is, you're on your own now" to some
> >very nice docs). Maybe a set of guidelines or a template for docs for
> >user-contributed products would also be useful.
> 
> I will respectfully vote against setting any level of standards in
> that arena.   Here's my argument.  While there are many fine
> developers who have the intent of creating a product for
> distribution which is for all practical purposes a commercial
> grade deliverable (with docs and all).  I would not want to set
> this as the standard.   If this level of 'compliance' becomes the
> norm, then we could easily loose half of the contributions that
> are currently in place.   These contributions have been made
> by indoviduals who have developed something for their own use
> and have tossed it into the community 'as-is' just in case some one
> else can find benefit from it.
> 
> I do appreciate being able to install a product and have it work like
> a champ with documentation, however being able to work through
> someone elses contributed code to see how they did x-y-z is of
> huge benefot to me as well.   It would be a shame to loose these
> resources just because we demanded that the contributor actually
> become a literary author as well as code author.
> 
> ... just my ($1.00/50) worth.

-- 
---------------------------------------------------
Ph: (734) 764 3377 
Email: darcyc@engin.umich.edu
URL: http://www-personal.engin.umich.edu/~darcyc/
---------------------------------------------------
'If you're not part of the solution, you're part of the precipitate'
..... Steven Wright