Bitching about the documentation...

[Steve Holden]

Paul Rubin wrote:
> skip at pobox.com writes:
> 
>>Sounds like a subject matter expert is needed here, not a garden variety
>>tech writer or Python programmer.  Documentation of esoteric stuff requires,
>>well, esoteric knowledge.
> 
> 
> Yes, that's what I mean; coding a library module for an esoteric
> function requires that same esoteric knowledge, and those are the
> modules for which the docs need the most help.  So the person coding
> the library module is the logical person to write the doc.  The doc
> writing task can't in general be handed off to some random programmer
> or writer.  It should be written by the same person who wrote the code.

Or, better still, by an accomplished writer who has access to the code's 
author. This was indeed my experience in writing the docs for previously 
undocumented modules. The author was happy to help me by answering 
questions, and this did make the docs better than they'd otherwise have 
been.
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC                     www.holdenweb.com
PyCon TX 2006                  www.python.org/pycon/