[development] Counting .info files [Was: Documenting contribs]

[inkfree press]

"Michelle Cox" wrote:

> This preserves the
>> contributors' autonomy while
>> encouraging quality improvements. I do agree that the module
>> descriptions are often of poor quality.

Autonomy, schmautonomy.

This is not an issue of civil liberty. We're talking about lucid, coherent,
accurate information displayed in a consistent way in a public space.

It's called editing, and it's quite reasonable to expect that one's writing,
when published to a distribution system, might be edited for clarity,
consistency and style -- without any need to "tell you in advance", have an
argument over grammar versus personal preference, or any other such thing.

Drupal.org is a big, giant, unwieldly-in-places published "magazine" (i.e.,
"container") of written content.  The application of a style guide, the
involvement of editors and other kinds of "this need not involve a
diplomatic meeting of the heads of egos" professional polishes should be
expected, desired, and considered a fact of life for any published writer.

I agree with Michelle about filing issues in the queue for simple edits to
teasers/descriptions: no way, Jose.

If a maintainer follows up on her or his project page then they will be
quick to notice editorial or style changes.  If they strongly wish to undo
that editing work, then there isn't any real mechanism to keep them from
simply undoing it.

There is a balance needed between "freedom of self-publishing" and the need
for a whole software system of great complexity to enforce some style
guidelines, whatever they may be and however they may change over time.
Various soft and hard policy decisions affect this relationship. Right now,
the maintainer could put whatever she wanted there, whether it was
intelligible or not (too often, it is not.) This is not the current debate,
but it is relevant.

In the "real world", you wouldn't even be writing or controlling the edits
on your published documentation -- you would write your code and hand things
off to a documentation department or staff.  And you would be thankful to
that staff because it meant you could do what you do best: write code.

Filing an edit in the issue queue is a non-starter as far as organized style
effort goes.  That's already possible just by posting a "feature request" or
other issue.  Anybody can suggest that you go and edit this or that
sentence, and they should, if they don't understand what you mean. But for
some kind of planned clean-up and harmonizing, well, that's just not
efficient and will never produce results.

Maintainers should be overjoyed that someone will improve their description
and help break the "I made it so I understand it perfectly" assumptions
which tend to creep into self-written documentation as well as generally
spruce up the copy.

Anyway, it's not such a big "my rights, my rights" deal. It's publishing.
-- 
inkfree