> Now, compare that to what happens when I search for the same in Python. I get this:<p>> <a href="https://docs.python.org/2/library/re.html" rel="nofollow">https://docs.python.org/2/library/re.html</a><p>I clicked and I saw the kind of technical documentation I love to read: precise, with examples. There is an introduction to Python's flavor of regular expressions, which highlights the potential problems (backslashes). This is not targetted at novice <i>programmers</i>, though.<p>> That’s the generic re library page. I have to scroll down to see which function I need.<p>Did you notice the table of contents on the left?
You might want to try Ctrl+F. But you might have to scroll down too, I don't deny it. You have to read, too.<p>> And even then, all I get is a hundred words of generic description. No examples.<p>Ctrl+F "example" highlights the table of contents. There is an example for "findall".<p>> I then have to Google Python regex findall examples, and go through a dozen blogs written in 2008.<p><a href="http://lmgtfy.com/?q=regex+findall+example#" rel="nofollow">http://lmgtfy.com/?q=regex+findall+example#</a><p>Not really, there are plenty of recent posts (stackoverflow, etc). And having articles from 2008 would not even imply that they are incorrect. In order to see how old your post is, I have to look at the source, but even though it is quite recent, it contains factual errors.
You know what puts off beginners?<p>Articles plagued with stuff like "this is horrible", "this is shit" and so on and son.<p>I see too often articles that just try to denigrate other technologies, saying that they suck, they are horrible, they are shit, they should be considered harmful, etc, just to try to make the author sound smart-assed.<p>The truth is that most stuff is the way it is for a reason. Maybe the situation has evolved and the reason is no longer valid, or maybe the people that built the thing had different goals than you. But understanding why it was valid for the other person and why it is maybe not valid for your use-case in an empathetic way will only make you a better engineer. We are all smart people trying our best to achieve something using technology. We are on the same boat. Let's stop insulting each-other.<p>If I was a novice and saw and article like this, I don't think I would want to hang out with such an overreacting crowd. Python is a libre project: instead of insulting other people's work to sell your book, try improving it. I can understand why proprietary software sometimes sucks -- it is disempowering -- but with libre software you are just kindly given a gift. If you don't like it, improve it and give back to the community, don't denigrate.
I pick Python up maybe 3 or 4 times a year - usually to automate something or to explore some algorithm in a notebook - so I'm pretty much an eternal beginner (in respect of the language, rather than the development process). This means I'm hitting up the docs pretty much constantly and I do find them mildly frustrating. It's an organisation thing. As someone stated up thread, the docs are really comprehensive, which means they resist skimming. There's no distinction between - say - a language <i>guide</i> and a language <i>reference</i>. As someone coming at Python from a comprehensive background in other PLs I just want to see a damn example, I don't want or need to read a treatise on operator precedence or regex syntax. Fortunately this problem is easily solved by adding the word 'example' as a search term - and then going back to the super comprehensive docs to find out what I just did wrong with my regex syntax!<p>For a <i>complete</i> beginner, the documentation for most any language is just line noise at first, until you gain the appropriate context (for which there are a pile of easily googleable resources) and thereafter the more comprehensive the better because you don't know <i>what you don't know</i>.<p>Maybe if there weren't eleventy bajillion easily accessible 'how to X in Python' articles or SO wasn't a thing there would be some pressing need for differently organised docs, but there are and it is, so y'know, meh.<p>Edit: over opinionated autocorrect.
I think the Python docs are fine. I use them all the time. (The re docs in particular.)<p>It's not beginner-focused, but it'd suck if the current docs were replaced with docs for beginners.<p>The re page has over 7,000 words. I need those 7k words. They help me get things done.<p>Perhaps a solution might be something like a <a href="https://simple.docs.python.org" rel="nofollow">https://simple.docs.python.org</a> type site: A simplified version, parallel to the existing documentation, consisting mostly of examples. I'd use it.
I've never encountered the "X requires unstated requirement Y, which fails to build because of obscure compiler error" issue, I would have liked if the author named X and Y.<p>However the documentation is totally a fair point. The "re" module is an excellent example - it starts off with a handful of relatively verbose introductory paragraphs and then dives straight into an extremely comprehensive list of special characters. The good news is that all the information you need is there <i>somewhere</i> but sadly it's hard to get there. Another commenter pointed out the Table of Contents, which for some reason my eyes just completely ignore by default. Maybe the font colour doesn't contrast with the background (aquamarine-ish on blue) or the line-spacing makes it tough. Certainly the numbered prefixes do not help, or the fact that the headings aren't actually particularly useful (sorry if you're responsible for the documentation, I like it overall I'm just searching for reasons why it's hard to read the side-menu).<p>I wish I had the time to help out, and the UX know-how to contribute to making it better. I'd feel awful if I pitched in and made things <i>worse</i> :(
The typical narrative of the mediocre duct tape engineer.<p>"I want to put something together fast by trial and error, without having to go through actual thinking or understanding. I don't care about details, just give me an example that I can copy, paste and duct-tape with another piece of code, so I can ship my product and charge some idiot a fortune for some spaghetti with meatballs code."<p>Documentation does not necessarily have to follow the format of a tutorial and can vary in levels of detail. Tutorials on this topic do exist. There, LMGTFY: <a href="https://docs.python.org/3/howto/regex.html" rel="nofollow">https://docs.python.org/3/howto/regex.html</a><p>How did I find it? Google: regular expression site:python.org
I've been learning Python as it seems to be the preferred language in education at the moment in UK and I'm expecting my kids to be using it. I work in arts & craft but have a strong hobby background in computers.<p>I started with a Coursera course <a href="https://www.coursera.org/learn/python" rel="nofollow">https://www.coursera.org/learn/python</a> which was pretty easy (you can run the videos at 1.5 or 2x).<p>That course is based on a free gratis book by the lecturer (there a chapter on regex that covers re; with examples too).<p>I took a good few hours trying different IDEs and settled on PyCharm community edition, it has very easy doc lookup. (<a href="http://alicious.com/editors-ides-python-code/" rel="nofollow">http://alicious.com/editors-ides-python-code/</a> is a brief summary of most of my IDE-for-python search.)<p>Currently I'm doing the Web Data course (using Beautiful Soup) and the only problem but is that <i>by choice</i> I'm using Python 3 when the course is written for 2. It covers regex pretty well.
I'm kinda surprised about the community argument. I've generally felt that people are nice enough, if a bit conservative. Though I guess this is the community that produced Python 3k, so something must have gone wrong<p>Especially to hear that someone went from Python to Ruby... I still feel raw for getting yelled at in IRC for trying to understand how blocks differ from anon. functions and about not doing things the "Ruby way"
I feel a big problem with Python these days is that it's not one Python community. It really is becoming more and more fractured and efforts go into weird places.<p>For instance we have the core developers which do Python 3, then we have some separate volunteers that work on the packaging infrastructure which is largely based on cobbling systems on top of the horribly broken distutils/setuptools setup. For documentation people don't want to touch it that much because which version should it go in? Python 2 which everybody is using or Python 3?<p>This schism in the community is causing more and more issues as time goes on.
2 out of the 3 negative points talks about how horrible the documentation is and yet I almost every day see blog posts, tutorials, books etc being posted online. If it really is so horrible why are these 'authors' apparently, not contributing to those horrible docs to make them better?<p>The gripe about packaging however is justified in a small manner, although we are way better than we used to be.
Once there was a discussion on HN about a specific command line tool, how easy command lines were and how even an idiot should be able to install and use it. I decided to test that theory by attempting to install it on a fresh copy of Windows, and documenting every step. I did get it installed, but did not succeed in using the command line tool for the desired application. There was also a number of difficult steps that nontechnical users would not know anything about and get frustrated by or turned away from. There were serious mistakes in the instructions. The biggest issue was dependencies which had further dependencies, all of which had their own difficult installation instructions. At least it didn't require compiling anything!<p><a href="https://news.ycombinator.com/item?id=11453086" rel="nofollow">https://news.ycombinator.com/item?id=11453086</a>
The trouble I had installing numpy, scipy and theano on python was over 3 days and only numpy & theano works.<p>3 days to go over the internet find out what the error... then trial and error.<p>Yes its difficult. And as the author says,"people get down voted"
Remember that Python is several decades old, and version 2 is about 16 years old. Like UNIX man pages, the docs (as well as best practices, idioms, etc.) were influenced by programming methods of the day. There was much more time to read the docs, think, and experiment. There weren't many answers to be found.<p>The methods of the modern developer are much different: 1) run into problem, 2) look for library to solve problem, 3) install library from package manager, 4) look for examples of library that fit problem, 5) copy-paste-modify example, 6) commit.<p>I can see why the docs are insufficient for today's beginners.
If python documentation is bad then, god forbid, these poor users should try to use anything else such as node.<p>As far as technical documentation does, the python documentation is usually ranging from pretty good to very good.
I can't believe an advertisement has gotten so many up votes.<p>The only problem I had when learning python is that it took me a while to figure out that you have to put __init__.py in every folder. Easiest language I've ever learned and made projects with, and I had previously learned Java/C/C++/Erlang
1st problem, do pip install pip --upgrade in your virtualenv as the 1st thing. Another possible solution, install the corresponding .rpm/.deb package<p>2nd problem: go to this page first <a href="https://docs.python.org/3/py-modindex.html" rel="nofollow">https://docs.python.org/3/py-modindex.html</a><p>3rd problem: yeah, kind of. Except for the logging module. Eff the logging module, it's a "java made in python" crap
>Installing libraries<p>I think pip and easy_install solves this problem. Or did I read the point incorrectly?<p>>docs are horrible<p>Also I never had seen the JS documentation of Mozilla, it is just beautiful. I have been using Python without any documentation related problems for that time, I actually am fond of Python documentation, for some reason it struck a chord with me.<p>The thing is, I learned Python by using the docs as the starting point, studied the tutorial and later the standard library, never really had a problem sorting through the docs ever. For everything there is a global module index, go to the a-z, click on a, go to the respective class/function and it has a good example, at least for the stdlib<p>I love Go language's docs more though.
Is there a good place to go for critiques on your project's documentation?<p>I'm currently working on updating the API docs for the company I work for, so we're paying people. However, what should open source projects do?<p>One thing I've seen that works poorly is encouraging new contributors should work on the documentation. The problem with this is that a new user only has knowledge of what they are confused by--not the broad understanding of the project that allows them to compose a document that teaches a coherent mental model. It seems like that can only be done by someone who is familiar with the project, but then they need a way to test that their writing actually makes sense.
I really like python, I use it all the time now and I don't start any new stuff in Ruby. But it was a struggle to get over the hump. I pretty much never use the Python docs, for the author's example, I would just google 'python array length stackoverflow'. I would only look at the official docs if something piqued my interest and I wanted to know more. Whereas with Ruby I go straight to chapter 4 of the pickaxe book and it answers the question 99 times out of 100. Also because its a PDF it works reliably on the train! I would dearly love to find a similarly written reference for python.
I see many people like python docs, and I agree, but the article talks about the difficulty for __beginners__.<p>That being said, maybe the python docs need something equivalent of wikipedia's 'Simple English' definitions.<p>Maybe by adding a 'simple' prefix (ie: simple.docs.python.org/3.5/library/re.html) that takes us to the very simplified version of the current documentation. Links to the in-depth docs are obviously necessary as well.
Here's a cached version (thanks, Google!) since the site seems to be down: <a href="http://webcache.googleusercontent.com/search?q=cache:3GQ0z6zB72cJ:pythonforengineers.com/this-is-what-python-beginners-have-to-deal-with/+&cd=1&hl=en&ct=clnk&gl=us" rel="nofollow">http://webcache.googleusercontent.com/search?q=cache:3GQ0z6z...</a>
>> 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.<p>If package maintainer does not specify dependencies, what can be done, really?
oh please, don't compare python docs to php docs, php docs show one function per page, because their api is WRONG, python shows them often per module level, how to compose the api of a module and use them with actual examples, the doc is useful for experienced developers.<p>I feel this article is advertising their book, maybe the only point to consider is the somewhat broken status of pip that have to deals with system libraries dependencies, but whatever, I still use pip every day and with multiple production deploys.<p>Is there some good comment about python docs, packaging management, that isn't so much a rant?
I'd like details on the "installing libraries" comment. for python, most distros come with a package, otherwise compilation is rarer.<p>If compiling python, or even something like opencv that requires compilation on any random linux distro - yes, you need to be able to figure it out. linux distros aren't all standardised.
Maybe instead of trying to teach others with a 'book project' he should try teaching himself and learn the actual language then he wouldn't have these kind of imaginary 'issues'!!