[development] Documenting contribs

[inkfree press]

> James Walker wrote:
>>> i think it is within the spirit for site maintainers to improve
>>> project descriptions as they see fit, and without prior approval from
>>> module maintainers. an after the fact email like: 'i fixed your stink'
>>> is sufficient. maintainer could always edit again if needed.
>> 
>> 
>> +1. Please :)

"Earl Miles" wrote:
> This is fine, but the last time I had someone 'correct' something for me, they
> didn't understand what I was doing and got it wrong. So there's something to
> be said for at least acknowledging the module maintainer here.

Well, there are coders, their are docs writers, their are marketing folks,
their are project leaders, and so on.  Each must communicate openly with the
others, granted.

But there is nothing wrong with flat-out saying:  Some folks make a great
module but can't write a description of how to use it that's worth the time
it takes to read it.  Nor should they feel bad because of such.

I don't think the chemist who invented shampoo is the same person who
crafted the perfectly expressed:

    Wet hair. Lather. Rinse. Repeat.


This is way better than the original bottle text:

    Saturate the protein strands of the head with H20. Apply approximately 1
ml of our glycerin-based fat derivative to the palm of the hand. Increase
the kinetic energy of the molecules surrounding the cranium through the
application of friction, rotational spin and torque -- best done by rubbing
the hand around and over the cranium at a nominal velocity with enough force
to keep the palm in contact with the cranium.  As the kinetic energy
increases, the fats suspended in the glyercin-based mixture will begin to
break down and absorb oxygen. This will produce a lather of mostly air. The
free electrons produced by the added force and chemical breakdown will cause
particles of dirt, dead skin cells, oils and air-based pollutants to break
free from their weakly charged bond with the protein strands and remain
suspended and electrically bound in the fatty lather.  Rinse the entire head
with warm water to remove the broken-down fatty lather, thereby rinsing away
the now-bonded undesirable molecules. Repeat.


They're both a swell read, but one is better for the end user.

;)


Your point about involving the maintainer is well-said and well-heard. No
one can really document a thing they don't understand, and the only way to
know if they got it right is the maintainer to have some input in the
revision.

It seems like Michelle is making this point really clear, and it's good that
maintainers are interested in the documentation and explanation of their
work -- I think it will work out for everyone's benefit.

-- 
inkfree