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.
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
I will respectfully vote against setting any level of standards in that arena.
Providing templates for documentation works well if you don't push it too much (as in require it to be there). I used Userland Frontier for a long time, and in Frontier when you create a 'suite' (a common way to distribute Frontier stuff) it comes with sample doc templates. If you don't want 'em, delete 'em, but otherwise it's easy enough to fill in a few blanks and provide some info for people. Julian.
participants (3)
-
Darcy Clark -
Julian Melville -
rgines＠purina.com