This is the story of many beginners. You start off all excited. Golly gee, I’m learning Python, I’m building stuff. It’s all fun and games, till you go beyond the bare basics. And that’s when the nightmares start.
I recently had the misfortune of creating a virtual machine for one of my book projects, and was surprised to find about half my time was wasted installing libraries and dealing with horrible documentation. Writing the code, writing the book, then making videos only took half the time.
Since many of the libraries I was working with were new for me, I felt like a beginner, and shared many of their pains. And I realised the crap beginners have to put up with. But no one talks about it. Those who do get attacked or downvoted. We seem to have a Python beats me, but only because it loves me mentality. And for this reason, I put off writing this blog for a long time. But you know what? Someone’s gotta talk about these problems.
Ready? I will take you through the broken system many people struggle with.
1) Installing libraries
I tried to install X. But when I ran it, it threw up a generic error, which meant (after Googling) that it needed Y. Okay. So I installed Y. But Y needed Z. And Z needs a C/C++ compiler. Okay, I’m on Linux, I have those.
But no. The compiler fails with a random error. Googling it takes me page after page where the top answer is: Fucking Google it, or What Have You Tried (whose author says he regrets writing the article now), or even plain Learn this shit before asking questions, you idiot.
I’m guessing about a third of the beginners quit at this stage. They either don’t use that library, or, use another language.
(Side note: Conda fixes some, but not all of these problems).
2) Horrible documentation
This problem was brought to my mind by a post on Reddit. Is it me or Python’s documentation very poorly organized.
No, it’s not you. The documentation really is shit.
The post above links to: The Python documentation is bad, and you should feel bad.
Don’t go ahead until you’ve read this!
The author, Sven, talks about how PHP has such simple documentation. You want function X? They’ll give you the definition, plus examples. While in Python, you have to trawl through heaps on dense text.
As someone who’s used a lot of C/C++, I am used to simple and easy to use docs. So when I google for regex search all C++, I get this page:
http://www.cplusplus.com/reference/regex/regex_search/
Like all C++(and C) docs, it gives the function definition, a description of variables and most important, a simple stand alone example. I usually go straight to the example.
Here’s the same search for PHP:
http://php.net/manual/en/function.preg-match.php
Again, simple to follow, with easy examples.
Now, compare that to what happens when I search for the same in Python. I get this:
https://docs.python.org/2/library/re.html
That’s the generic re library page. I have to scroll down to see which function I need. And even then, all I get is a hundred words of generic description. No examples. I then have to Google Python regex findall examples, and go through a dozen blogs written in 2008.
3) Horrible Tutorials / Examples in Libraries
Related to the above, even the tutorials or the official documentation of libraries is horrible. That is, when they have examples. One famous library gives nothing but API calls. They should just put a big middle finger to the users on the front page.
When you have examples in libraries, they fall into:
a) Here is the simplest use case. For the rest, read the code(which we will change without telling you, and not update the docs). Good luck!
b) Here is an overly complicated 10,000 line example that introduces twenty different concepts that will have you scratching you head for hours. We know you have nothing better to do with your time. You are using Python, after all!
One library creator starts off his documentation by teaching you how to write setup.py files (for creating Python packages). He then spends ten hours talking about how to create packages, and only five lines of how to use his library. Why? Because this is Python, dammnit, and we do things properly ’round ‘ere. You want to use my library, you first gotta learn all this other shit you will never use.
And most of the tutorials seem to follow this mentality. There are very few tutorials that just give you the code of how to use Feature X. Instead, they will throw in a dozen other concepts. And expect you to sort out what you need.
You know who uses simple, self contained examples and tutorials? Every. Other. Language. In. The. World.
By this stage, most people have quit or gone back to other languages. And I don’t blame them.
4) Where Python is Getting Better: Community
Like Sven said in the linked article above, the community is getting better, at least on Reddit and Stack Overflow, where I guess most people hangout.
I still see the occasional This is the way we do things ’round ‘ere, a blind adherence to Pep8 (and a tendency to treat all Pep documents as religious texts; I can’t remember how many debates have been shot down because someone pointed to a dead PEP written 10 years ago).
That said, it is getting rare; I think many Pythonistas took Steve Yegge’s words to heart when he called the Python community’s frost problem, ie, a general unfriendliness towards beginners(Steve was one of the early Python programmers who left for Ruby). Nowadays, there are millions of resources targeted specifically at beginners, and forums that encourage questions (like Reddit’s Learn Python).
I added this section later, just to show you that things can change, if people are willing to accept there is a problem.
In closing
If you are a beginner who has been struggling: It’s not you, it’s the system that is broken. Even experienced programmers struggle with the same things. You just get used to licking your wounds and continuing.
(Sorry to end on a downer. Here’s a pic of a cute puppy getting a massage to lift your spirits)
