[Doc-SIG] Improving the documenting process.

[Chris Jerdonek]

On Jan 2, 2006, at 5:17 PM, Laura Creighton wrote:

> Chad suggested I post this reply to him back to doc-sig, and see
> if there are others like me who think that the python documentation
> problem centres around 'not enough good documentation being
> produced' and a process that is opaque, has bottlenecks, and
> excludes the very people who would be best at writing good
> documentation, because they aren't python-language developers.

I really appreciate reading the thoughts Laura has expressed over the 
last couple e-mails.

I've only been on this list for about a week.  I'm in the camp of not 
being a python-language developer, but I can't say yet whether this 
qualifies me as being good at writing documentation...

Some thoughts below.

>> Next we discovered that most people wrote better
>> if they wrote with somebody else. (For non-fiction.  For fiction we
>> couldn't come to any conclusions except that we needed to study the
>> cognitive process of writing fiction more.) On the other hand, 
>> documents
>> designed by committee almost never were well written unless the
>> committee met, decided on the structure of the document and what
>> its content was to be, and then let one or two people actually write
>> the thing.
>> ...
>> Wikipedia is proving that you can do
>> continuous updates on documentation.  Do we need them?  Would we
>> get more people working on improving the documents if the live
>> version was a mediawiki?

The contrast here is interesting.  Do these observations conflict in 
any way?  Do wikis have more or less in common with "writing by 
committee"?

I wonder how wiki documentation compares to the best 
individually-written Python documentation -- if the style gets 
watered-down in the community process at all, and whether this 
dissuades any writers.

>> I think the question of 'what do we need in order to share and
>> collaboratively work on documents more effectively' is the one that
>> we need to solve if we want more rapid turnover.

Backing up here, how does the documentation group judge success, or 
what is its purpose?  Is it about creating an authoritative manuscript, 
or facilitating learning by more people?

Also, there's one thing I'm still confused about.  Where do people fit 
in who are interested in creating documentation for a specialized 
Python module that's not part of Python's core?  Ideally, would the 
documentation group supply and empower that person with the tools 
needed to write and disseminate documentation on their own, or would 
they become de facto members of the Python documentation group, 
contributing to the official body of Python documentation (albeit to a 
small corner of it)?

--Chris