On Aug 7, 2009, at 10:48 AM, alex23 wrote:
Kee Nethery <k...@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
--
http://mail.python.org/mailman/listinfo/python-list
