On Fri, 07 Aug 2009 13:35:26 -0700, Kee Nethery wrote:
> > 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 The last one is actually wrong, because the Python bug tracker is indexed by Google. As for the rest, you're right that the current bug-tracker puts up barriers to people submitting comments and bugs. That's actually a good thing. The only thing worse than not enough information is too much information, and the current situation does a good job of discouraging the sorts of people who submit bad bug reports (e.g. duplicates of bug reports, bug reports for things fixed years ago, bug reports that are due to mistakes in their code, etc.). > 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 Disclaimer: python.org is down at the moment, so I can't check that page to see precisely what you're talking about. > 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. Er, that would be a bug in the IDE, surely? Inside strings, # is an ordinary character with no special meaning. >>> s = "this is a string with an unescaped # in it" >>> s 'this is a string with an unescaped # in it' The Python docs are supposed to be about Python the language, not work- arounds for IDE bugs. [...] > 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). Good. As a newbie, you SHOULD assume that anything you think is a bug is probably a bug in YOUR code, not Python, and the same goes for documentation bugs. If you don't understand something in the docs, chances are that it's a problem with you, not the docs. Your first port of call should be the tutor list, or here, and not to "fix" the docs by putting in noise that just gets in the way of the intended audience, namely experienced developers. > 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). No, we care. We just don't want to have the docs filled with all the hand- holding and introductory stuff which the newbie needs. As a developer, you will outgrow the need for training wheels. Why force training wheels on the docs that you will be referring to for your entire career as a programmer, when you only need them for the first few months? There are plenty of docs aimed at newbies, and mailing lists where you can ask questions. Putting user-comments on a separate page separates the noisy, low-value comments from the good stuff, but it increases the efforts needed by the webpage admin (who is going to deal with the comment spam? who is going to go through the user-comments stripping out the total nonsense put in by helpful ignoramuses?). It works for Wikipedia, because there are tens of thousands of users contributing small amounts of effort, and hundreds putting in a lot of effort, but even there there is a major problem with vandalism. We don't have those resources. By the way, if a person wants to contribute, and can demonstrate competence, reliability, good-sense and trustworthiness, there's no reason why he or she couldn't get a check-in account for the Python docs. (All the Python docs are written by volunteers.) A good way to demonstrate these things is by submitting good-quality doc improvements to the bug-tracker. If a person can't be bothered to do so, because it requires effort to get an account, that goes a long way to demonstrating the *lack* of reliability which will disqualify them from the job. > 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. You don't need a login to view bug reports, only to modify them. If you want an open-access documentation system go right ahead and build one. There are plenty of wikis available to use, and the Python docs are freely available as your starting point. I might even contribute myself. I just don't want it mixed in with the official docs: I want a clear separation between what's officially sanctioned and what's not. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
