Bitching about the documentation...

BartlebyScrivener rpdooling at gmail.com
Tue Dec 6 05:14:24 CET 2005


>>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. <<

Now you're talking. The writer forces the programmer to explain how the
code works, in plain English, until the writer understands it. Then the
writer creates simple sentences written in the active voice with vivid
particular examples to illustrate. Voila. 

rd




More information about the Python-list mailing list