[python-advocacy] Python makes the "most wanted list"

Jeff Younker jeff at drinktomi.com
Mon Feb 11 19:08:46 CET 2008



On Feb 11, 2008, at 5:36 AM, Facundo Batista wrote:
> 2008/2/9, Michael Pittaro <mikeyp at snaplogic.org>:
>
>> We could probably update the urllib documentation to strongly  
>> encourage
>> setting the User-agent header. The examples already show how to do  
>> it,
>> but if urllib2.urlopen()  is the popular function, adding useragent  
>> as
>> an argument to might be worth considering
>
> Setting the useragent, as any header, is plain easy.


Adding a feature, and putting a note in the documentation is not
enough.  People don't read the documentation in enough detail.  If
the library is leading to a problem, then the default for the library
needs to be changed.

Why do I argue this?

1) People aren't going to take note of the change in the documentation.

2) A lot of scripts don't get any appreciable maintenance, so changing
      the documentation won't affect these.

3) Fixing the module will result in all the software being changed as
      python versions are updated.

- Jeff Younker - jeff at drinktomi.com -



Why do I believe #1?   At session at LISA 2000 I attended a session
called, "Why the documentation sucks, and what you can do about it."
The speaker was tech writer. He recounted an occasion when he
did lab experiments with the documentation.

The company he worked for had changed an OS tool's behavior.
The change was noted in the new documentation. The warning was
clearly set aside from the rest of the text.  The manual was given
to a group of people who's assignment was to read the manual,
and to use the tool.

In the first round nobody read the warning, and everybody misused
the new version of the tool.   So they made the warning bigger, and
reprinted the manual.  Still no change.  This process continued
until the warning was 48 pt bold text set on an independent page
(I believe) in a bright florescent color.  And still nobody noticed.

The only solution that worked was changing the software so that
it behaved as everyone had expected it to.  No amount of
documentation was sufficient to affect the change in user behavior.


More information about the Advocacy mailing list