.. title: Why I don't feel so bad .. slug: why-i-dont-feel-so-bad .. date: 2013/02/20 09:45:00 .. tags: python .. link: .. description: Yesterday I came across a post titled `The Python documentation is bad, and you should feel bad `__. It made me feel a little bad, but not too much. Here's why. Weighing in at over 2,000 words, it makes a few decent points, but it makes broad conclusions based on small samples, and makes a few cringeworthy points towards the end. 200 words would have made the relevant points, or just a bug report or two. That's not as fun as writing a rant, though. I disagree heavily with a few things he wrote about, namely what I think is a view of the community clouded by a lot of other negativity he was feeling around the topic of documentation. It's no secret that our documentation can use some work, but I think the community gets a bad name here when it isn't called for. There also seems to be a misunderstanding of how work gets done. The Community ============= The section on "The Python Community" was pretty unfair and doesn't really seem to reflect reality. While it states that the section isn't all about #python, it's pretty clear that the poster's experiences with #python colored his beliefs. Unfortunately, the IRC channel isn't always known as one of the most friendly places to find help. That sucks, and I hear from some trusted folks that it's changing for the better, but it is somewhat of a common opinion, so I'm not 100% surprised he feels that way. The later mention of fanboyism, specifically towards Twisted, likely comes from his experience in #python, because that's one of the few places I consistently saw Twisted being recommended. They get a ton of questions every day, many of them repeats, and they probably try to limit the set of answers they need to give. It's a very busy channel and they try to help as many people as they can, so they need *something* to make it easier for them. Whether or not you like Twisted, it does solve a lot of the network questions people have. I'm with the author that being told "just use Twisted" isn't always helpful and isn't a possibility in some cases, but it doesn't make the whole community unhelpful and hostile. Just like "install linux" isn't a helpful answer to "How do I install pywin32?", which pops up on Reddit here and there, sometimes you just need to ask in another place to get more (useful) opinions. Hostile and unhelpful would be some of the last things you could say about support avenues like comp.lang.python or Stack Overflow. The post has an edit to clarify that his opinions don't seem to apply to Reddit and Stack Overflow, which is good. However, I don't see the differentiating factor between any of those sites and the many other communication channels. One the author attempts to provide is "communities that consist mostly of Python developers, and do not have a very distinct culture of their own," probably referring to mailing lists. Having participated in all of these sites, mailing lists, and IRC channels, it still looks like the painting is being done with an awfully wide brush. Community Norms =============== "The general norm for the Python community appears to be that if you are not already familiar with the language, you do not deserve help," is something that could not be further from reality. How many beginners books do we now have? How much free introductory material do we now have? How many colleges, traditional and otherwise, are now teaching Python? There is no better time than now to learn Python, and the amount of resources has never been as plentiful. The `tutor mailing list `__, a resource for those beginning with Python, looks pretty active and helpful. I just looked at the February archive and what do you know? The very first post on that page is by Alan Gauld, author of "`Learn to Program Using Python `__". Funny story: My father was one of the reviewers of that book leading up to its publishing in 2000, and I wrote my own small review of the book (he gave me the $200 they were paying reviewers at the time, I bought a new baseball bat). His response is a wonderful showing right off the bat, and a quick perusal through the list shows some good help being given. `python-list `__ is another resource and tends to be for those who have gotten their feet slightly wet, but it's really open to anyone. This list is *very* active, and while I haven't followed it in years, a quick look through the archives shows the same generally helpful user base that I'm familiar with. When it comes to being involved in development efforts, we have the `core-mentorship list `__ that serves as a great place to get involved in a helpful and friendly atmosphere. Many beginners have come through this list and gotten started on their way to having their contributions accepted into the Python source tree. Even `python-dev `__ is good about working with first timers when they come up. PyCon, a conference generally stocked up with intermediate to advanced material, has two tutorials not only for beginners to Python but for complete beginners to programming as a whole. There are also two days of childrens tutorials being given *for free*. The `Python Software Foundation `__ has a committee devoted to helpful and friendly efforts. The Outreach & Education committee funds efforts around the world to teach Python to various groups of people. There's a budget and a list of excellent committee members, and a network of people around the world that are interested in helping the cause. The rest of the paragraph goes on with wild hyperbole about people saying you're horrible for having less than optimal code. I'm not usually one to say "cite your source," but, cite your source. I'm aware of the confirmation bias I have at times when it comes to Python being a nice and friendly place, but I'm well aware that it's not actually sunshine and roses. The community at large may need tuning as growing pains hit from time to time, but it's not a current issue as far as I've been made aware of. Reading the Source ================== Speaking of sources, the poster goes on to resist reading the source. While a valid point in general if you're just trying to find out the signature of a function, there's a lot to be learned by reading the source of code you're using. When it comes to Python, a language generally referred to as "readable", in some cases the code really is a good thing to rely on. However, it shouldn't be the only thing, so I can see why he got upset with it. Pointing people to the source isn't usually a good beginner response unless you can point them to where in the source their answer is going to be, and even then you have to make sure it's not going to overcomplicate what they're looking for. If we didn't have documentation for ``winreg.OpenKey`` and I told you to read the source, would you know it's a C file in ``PC\winreg.c`` of a source checkout that you likely don't have? No. He's got a valid point, but I would recommend everyone does take a look at the code they're importing and using at some point. It doesn't have to be a black box and you could learn a thing or two along the way. Mind Reading ============ Perhaps the most egregious claim in this post is that someone should be working on the points this author *just wrote* about. For one, in order for something to be fixed it must first be determined that it is broken. We tend to do that through the use of bug reports. http://bugs.python.org is open for business 24/7. I think the author does bring up some valid points about documentation that could use a discussion, so hopefully they are submitted. We don't know about them until you report them. What's obvious to one may not even register to others, so there surely can't be any effort underway when not everyone is on the same page. Keep in mind that it takes effort to get things fixed in an all volunteer project. It takes some effort to engage in a discussion, and it takes a lot more to complete the changes. However, I must say that I don't have high hopes for changes in this area if the reporter isn't interested in helping. Changing open source software isn't a drive-thru experience. Sometimes you have to get behind the grill and flip your own burger if it's not being served fast enough. The demand to "make it happen" was particularly funny to me, reminding me of Guido's "make it so" comment in his response to approving `PEP 414 `__ (if you don't get why this is funny, Guido created Python). This right here simply doesn't work, especially ending it with "that's what developers do." The author could stand to learn a thing or two about respect, given again that an all volunteer workforce isn't exactly waiting at the beck and call of everyone with a blog. A lot of the developers of Python work on things they want to work on in areas they're interested in. An overwhelming majority of us put in these efforts off the clock, hacking in the evenings or on the weekends, in order to contribute to a project that we like. Knowledge of that will hopefully result in a better tone moving forward (it's pretty much required). ---- In conclusion, I think what could have been said in a bug report or two became an unfair smear of the Python community. For me, the good points were mostly marred by trying to fill up a rant post, and I'm not optimistic that anything positive will come out of it. That's a bummer because we could always use some help.