Python docs disappointing - group effort to hire writers?

[Kee Nethery]

On Aug 7, 2009, at 10:48 AM, alex23 wrote:

> Kee Nethery <k... at kagi.com> wrote:
>> I'm looking forward to the acceleration of improvements to the
>> official docs based upon easy to provide user feedback. Glad to see
>> that the bug tracking system is going to not be the primary means for
>> documentation changes.
>
> I'm not sure what you see as being fundamentally different between
> open access to a bug tracker & open access to a wiki, other than it
> being a lot more difficult to have threaded discussion on a wiki.
>
> Why exactly is posting an open comment on a bug tracker somehow
> inferior to posting an open comment on a wiki?

It's a good question and deserves a good answer.

* Fewer Steps
* Immediate
* Does not need to be formally reviewed
* Easier to search

For all these comments, assume the starting point is the section in a  
web page that documents a specific python function. Assume the user is  
using the documentation for the first time in attempt to convert to  
Python. Thus, this is the only official Python page they have ever  
seen, they found it via Google and went directly to it. For example  
purposes, I'll use the following page:
http://docs.python.org/reference/lexical_analysis.html
Lets say the user is in section 2.1.3 Comments

Here's the scenario: The user wanted to include "#" in one of their  
strings and the IDE kept interpreting it as a comment. But they really  
need to use that character in the string. Eventually they find out  
that they can escape the character in their string so that Python  
stops thinking it is the beginning of a comment. They want other users  
to not suffer through the same thing, and they want to contribute to  
the betterment of Python, so they want this information saved so that  
others can avoid the mistake they were making.

* Fewer Steps:

With the bug tracking system, their only option is to lobby to get the  
documentation changed. Lets assume that Python experts all agree that  
the docs should get updated with this gotcha (which as a newbie, they  
are not sure that is a valid assumption and would probably just halt  
in their quest to get the docs updated). But assuming everyone agrees  
this is a valuable addition to the docs so that others can avoid the  
same error, where on this page dues the user submit this bug? There is  
no link on this page to the bug tracking system.

Lets assume they find the bug tracking system through determined  
efforts because they believe there has to be such a thing and they are  
absolutely sure the powers that be want their input. When they find  
the bug tracking system ... they have to create a user account. Then  
they have to wait for the confirming email. Finally they get access to  
the bug tracking system and being a good citizen, they want to make  
sure that they are not duplicating a previously entered bug. What do  
they search on? Do they search for 2.1.3? Do they search for "#"?  
Chances are, even if they do a whole set of searches, and if there  
really is already another bug entered for the exact same issue, they  
are unlikely to find it.

So they create a bug and now they need to go back and reference the  
link (find the page from their browser history) and type up why they  
think their modification to the documentation is worthy. Then once the  
bug is submitted ... you get the picture, there are a gazillion steps  
just to submit a bug. Most people do not bother to submit little  
helpful hints to the docs because it is too much of a pain to do so  
and there is zero confidence that as a newbie, anyone cares about what  
they found confusing, after all, they are just a newbie and not worthy  
of altering the documentation. (Certainly that opinion has been  
expressed several times on this mailing list).

With a wiki article tied to each section in the docs, they click on  
the link and are taken directly to the wiki page of user contributions  
for this specific  2.1.3 section of the docs. They scan the user  
comments and see that no one else entered a note about this gotcha.  
They click on the edit button, enter their gotcha, save, and they are  
done.

* Immediate:

With the bug tracking system, they struggle to find a place to  
contribute and then once they make their contribution, they have no  
idea whether anyone will ever see it and whether they have just wasted  
a bunch of time.

With the wiki link for that section, in less than a minute, they can  
see the comments they have left attached to that specific section so  
that others can see them too and perhaps avoid the same mistake they  
made. A wiki link encourages new users to be contributors. New users  
are the absolute best source of what is confusing to a new user.

* Does not need to be formally reviewed:

With the bug tracking system, each bug has to be reviewed by a  
volunteer, analyzed, commented on, dealt with.

With a wiki, no one has to look at user comments. They can just leave  
them there and ignore them. Other users can police the content and add  
additional comments or examples. All the while none of the official  
volunteers have to get in the loop. If some official volunteer wants  
to improve the docs, they can scan the wiki contributions and use that  
as the source for official changes to the docs.

* Easier to search:

Very few people would think to search the bug tracking system for help  
with some specific function. If someone is having trouble with the #  
sign in their strings, the bug tracking system is not going to be at  
the top of their list for search locations, especially when the bug  
tracking system is not mentioned and when found requires a confirmed  
login.

With a wiki link, the first thing someone will do is click on that to  
see if anyone else left notes about the specific problem. If there was  
no answer there, they'd search Google and try bunches of different  
wordings looking for some clue as to what is happening. I doubt most  
users (except for expert users) would ever search the bug tracking  
system for hints on why their code is not doing what they expect.

My 2 cents,
Kee