This Is What Python Beginners Have to Deal With

http://pythonforengineers.com/this-is-what-python-beginners-have-to-deal-with/

by reubano • 10 years ago

120 160 10 years ago

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?

The gripe about packaging however is justified in a small manner, although we are way better than we used to be.

afarrell2• 10 years ago

If the problem is fragmentation, there needs to be someone to project-manage the writing of the docs and, just as important, the user-testing of the docs. Much like the way the Django Software Foundation pays Tim Graham to be a steward of part of Django development, this probably means that the PSF should pay someone to be a steward of the user experience of the officially-sanctioned python documentation.

tobltobs• 10 years ago

I am always astonished how the Django project accomplishes to create such a great documentation with their limited resources. Have a look at their fundraising page: https://www.djangoproject.com/fundraising/ .

em500• 10 years ago

If it really is so horrible why are these 'authors' apparently, not contributing to those horrible docs to make them better?

Incentives (building their personal brand) is much more tilted towards blog posts, tutorials, books etc. than improving the standard documentation.

cderwin• 10 years ago

But if you're complaining primarily to further your personal brand (not because you genuinely want to see a problem addressed), why should your complaints even be taken with merit?

junke9• 10 years ago

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

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 programmers, though.

That’s the generic re library page. I have to scroll down to see which function I need.

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.

And even then, all I get is a hundred words of generic description. No examples.

Ctrl+F "example" highlights the table of contents. There is an example for "findall".

I then have to Google Python regex findall examples, and go through a dozen blogs written in 2008.

http://lmgtfy.com/?q=regex+findall+example#

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.

int_19h2• 10 years ago

Regarding the docs layout and "having to scroll down to see which function", I also don't quite get it. From my perspective, it's a very nice trait of Python docs compared to PHP docs, that the former actually explain how to use the various parts of the API together, before giving descriptions for every specific API. It's simply a much better way to digest it and learn to use it without making a mess (speaking of which and PHP...).

snovv_crash7• 10 years ago

Coming from statically typed languages, I've really struggled with the Python docs, because they aren't really clear with what is returned from a lot of functions, and which arguments are allowed. I end up finding an example where it is being used, then deducing from what they do with the result what was actually returned.

Contrast this with the ugly-but-functional JavaDocs, which can be auto-generated, and easily shows all return types and arguments for every publicly exposed function and member variable. I understand why this can't be done automatically in Python, but at least they could put the time in to make it clear in their standard libraries.

philipov• 10 years ago

The author has a vested interest in making people believe they can't figure it out themselves. The article is an advertisement for their book/videos.

jacobolus4• 10 years ago

Googling about Python regular expressions still returns the “Regular Expression HOWTO” near the top of the results. https://docs.python.org/3/howto/regex.html

That’s pretty much the best succinct introductory page about regular expressions (applying to whatever language) online, and has been for 15+ years. After finishing that page, a beginning python programmer should be ready for the library reference and/or a more serious book.

(No idea why the author here thinks that examples from 2008 are such a terrible thing. Nothing has changed about Python regular expressions in ages.)

Overall, the Python docs are amazing. Not perfect by a long shot, but miles ahead of PHP or C++. Pretty much the best programming language documentation I’ve ever used (but I admit there are many programming languages I’ve never tried). Perhaps that’s partly down to the language itself making a lot more sense than many alternatives. The docs don’t have to do as much work to paper over brokenness.

His take on the community also bears no resemblance to my experience. People on python mailing lists, IRC, local meetups, Pycon, etc. have unfailingly been friendly and welcoming and willing to bend over backwards to help newbies.

thr0waway1239• 10 years ago

I remember first learning about NLTK, not knowing the first thing about Python, or anything at all about natural language processing.

And I could just "get it". My lack of Python knowledge did not get in the way because it was like reading pseudocode. The language is so beautifully designed for the majority of the cases where you do any kind of algorithmic/math work.

In fact, it may have been too beautifully designed. :-) From what I can see from comment threads [1], most people seem to want to use NLTK even if there are a lot of complaints about how it is too slow for production, and how there are much better alternatives for NLP when it comes to performance. I think people are attracted to it because of its simplicity.

[1] https://news.ycombinator.com/item?id=7658977

huskyr2• 10 years ago

Quoting myself from a blog post i wrote when i was learning Python two and a half years ago [1]:

Let’s say i want to know how to do the Python equivalent of PHP’s foreach. The docs about the for statement say this:

    The for statement is used to iterate over the elements of a sequence (such as a string, tuple or list) or other iterable object:

    for_stmt ::=  "for" target_list "in" expression_list ":" suite
          ["else" ":" suite]

Right, so what does that mean? What’s ::=? What’s an ‘expression list’?

    The expression list is evaluated once; it should yield an iterable object. An iterator is created for the result of the expression_list. The suite is then executed once for each item provided by the iterator, in the order of ascending indices.

“Ascending indices”? “Suite”? This might be clear for a CI professor, but it’s not for the mere mortals that read the docs and want to get stuff done.

Things haven't gotten much better since then.

[1] https://www.haykranen.nl/2014/02/12/saying-hello-to-python-s...

jacobolus4• 10 years ago

You were reading the wrong docs for a newbie. The language reference is intended for people who want a very concise and precise technical document, not an introductory explanation. If you read the very beginning, the language reference is very clear about what it is and isn’t:

This reference manual describes the syntax and “core semantics” of the language. It is terse, but attempts to be exact and complete. The semantics of non-essential built-in object types and of the built-in functions and modules are described in The Python Standard Library. For an informal introduction to the language, see The Python Tutorial.

You should have been looking at the Python Tutorial instead.

https://docs.python.org/3/tutorial/controlflow.html

https://docs.python.org/3/tutorial/datastructures.html#loopi...

Illniyar2• 10 years ago

I think this is the exact type of comments that the author comes out against.

You aren't putting yourself in the shoes of a beginner.

Let's say I'm a beginner, and I want to just experiment with the language a bit (I've already read some tutorials or am not interested) - since I'm just trying to get the feel of the language and ecosystem, I'm not trying to get a deep understanding of the language and tools - I want to match a regex.

In the C++ and PHP examples he provided, the basic example is easily found - it's basically two actions - search in google and scroll to the example.

What you are suggesting takes several more steps - ctrl-f for a text that you might get wrong (you've searched for sample instead of example for instance), iterate until you get the right place, etc...

And that's assuming you even realize that you should run ctrl-f, why should you?

The main issue though is that if I'm a beginner I'm doing this kind of searches several times a minute - to have to stop and realize what to look for every time is extremely frustrating.

I've worked with Ruby,Python, Java and Javascript - python's (and django's) documentation is extremely verbose and rarely straightforward compared to the other ones.

junke9• 10 years ago

You aren't putting yourself in the shoes of a beginner.

How do you know if I am putting myself in the shoes of a beginner or not? And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? You can't expect a single document to be relevant for all kind of people. The reference documentation has a clear target audience, which apparently conflicts with what you expect from it.

And that's assuming you even realize that you should run ctrl-f, why should you?
(you've searched for sample instead of example for instance)

Okay, so you are talking about absolute beginners, with no experience whatsoever with programming. And the C++ and PHP pages are somewhat useful for them?

I've already read some tutorials or am not interested
Let's say I'm a beginner [...] I want to match a regex.

Now, you are saying that you already have experience with programming? Google "python tutorial regex" gives plenty of results, the first of them being currently "Regular Expressions HOWTO" (https://docs.python.org/2/howto/regex.html).

Absolute beginners need a teacher, a mentor, or a step-by-step book, or a very gentle tutorial, or an online REPL. That's fine. You can't please everybody in the reference documentation.

ubernostrum5• 10 years ago

You aren't putting yourself in the shoes of a beginner.

The real issue you and the author both run into is assuming that the wants, needs and learning styles of all people everywhere are identical. There's a good argument to be made for expanding the variety of styles and types of documentation available in order to cater to more ways of learning, but not a good argument to be made for suppressing or removing existing documentation since that boils down to "all right, let's cut off those people to focus on these people".

One big example that's not covered, but relevant, is how many (free, so potentially competing with the author's book) workshops or online complete guides to learn Python or Python-related tools have been popping up the past couple of years. Having an experienced coach who walks you through everything your first couple of days and gets you acclimated is a huge deal for some people (while others prefer to read on their own in an undirected way), but isn't accounted for in the article.

nnq2• 10 years ago

he kind of technical documentation I love to read: precise

Nothing precise about it. Method signatures don't even include a clear description of what they can f return! I have to go and fish this infos from the text blob below. Even JavaScript gives you a damn return values section for every method: https://developer.mozilla.org/en/docs/Web/JavaScript/Referen... . I can't expect a type signature like in OCaml or Haskell (yeah, H sometimes gives you only a type signature which is even worse...), but still.

The cool thing about Python is not the high quality documentation. It's that you can still be productive in it despite it being a dynamic language with such a horrible and fuzzy documentation :) Guido really did a fine language design job.

junke9• 10 years ago

The "text blob" always starts explaining precisely what kind of return value to expect under which circumstances. The return value's type can change depending on the context, and using plain text is somewhat easier to write and read than trying to come up with a dedicated notation.

See findall[0], for example. The structure returned depends on whether the regexp has capturing groups or not. A specialized notation could be designed to represent that, but as far as I am concerned, the textual string is good enough.

Just for fun, the return type could be expressed as:

      [string N]                 (A)
    | [(string M) N] : (M > 1)   (B)

    - Case A if the regexp matches N times without overlapping and without capturing any group, or capturing a single group.
    - Case B if the regexp matches N times without overlapping and, for each match, captures a tuple of M groups, as strings.

... where [type size] denotes a list of size "size" satisfying the type description "type". Likewise, (type size) is a tuple of "size" elements, all of which satisfying the same type. Or you could write t1 * t2 like in other languages to define cross-products.

[0] https://docs.python.org/2/library/re.html#re.findall

kawsper• 10 years ago

I am a Ruby guy, but we had a project where we built a forking socket server in Python, I was really impressed with the documentation.

https://docs.python.org/2/library/socketserver.html

https://docs.python.org/3/library/socketserver.html

rtpg• 10 years ago

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

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"

jbmorgado• 10 years ago

I also found that part odd.

At least in stackoverflow, compared to R community, I found python community to be more helpful and more polite.

dkersten5• 10 years ago

Agreed. The community is the part I like most about Python. I've largely stopped attending talks and such years ago, but still attend events every now and again (mostly the annual local conference) purely because I find the community friendly and interesting.

crdoconnor12• 10 years ago

1) is really something that the maintainers of pip should deal with but unfortunately they don't see it as their problem.

ubernostrum5• 10 years ago

pip's job isn't to specify dependencies, it's to resolve and install them. Specifying the dependencies is the job of setup.py, and that's not at all an unreasonable stance to take.

crdoconnor12• 10 years ago

Really? Does it resolve and install libpq-dev or postgresql-libs when you try to install psycopg2? Or even tell you that you need to install them?

The problem isn't that this can't be solved in a consistent, clear way. The problem is that nobody views this as their problem to solve.

talideon10• 10 years ago

I really don't know of anything like pip that can handle that case in any language, and I'm not entirely convinced that somehow resolving the plethora of naming conventions for packages between different distros (and even different vesions of those distros) is really the job of a language-specific package manager.

Nobody's done it because any potential solutions are much too brittle. On Debian derivatives, it's not too big a problem, but go outside of that, and even high-level tooling is a mess (the tooling on top of RPM varies from distro to distro, and even version to version). On macOS, if you're using a ports-like system, you might be dealing with fink, MacPorts, brew, pkgsrc, &c.

Any competently-managed project, OTOH, will list the dependencies for a number of major distros and OSs so that the person installing it will have an idea what to look for.

I'm all ears for a reasonable solution to this, if you have one.

dkersten5• 10 years ago

I really don't know of anything like pip that can handle that case in any language

I've never ever had to think about it with the Java ecosystem. I just get a jar and stuff magically works.

yxhuvud• 10 years ago

The solutions are only brittle if the different distribution systems doesn't talk with each other. Someone should gather a bunch of different language level package managers and a bunch of distro level package managers in a room and then not let them out until they have figured out a standardised API to declare, provide and require dependencies.

crdoconnor12• 10 years ago

I really don't know of anything like pip that can handle that case in any language, and I'm not entirely convinced that somehow resolving the plethora of naming conventions for packages between different distros (and even different vesions of those distros) is really the job of a language-specific package manager.

I actually started probably the only project to actually make a stab at solving this: https://github.com/unixpackage/unixpackage

However, I'm loath to continue working on it because there are few tasks more tedious, filled with annoying edge cases and thankless than this. Plus I know it would never make it into pip because "it's not pip's job".

I'm all ears for a reasonable solution to this, if you have one.

The only one I can think of is to packages like libpq-dev and libjpeg-dev and even the C compiler installable via pip and get the maintainers of pillow/psycopg2/whatever else to remove all their horrible hacky code to look for these dependencies on the system itself.

This will balloon the size of virtualenvs and increase installation times but it'll be worth it. Not only will it eliminate those horrible installation errors making everybody happy (not just beginners), it will eliminate a nasty source of brittleness (subtly different behavior caused by different versions of these packages on different platforms).

adontz• 10 years ago

> 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.

If package maintainer does not specify dependencies, what can be done, really?

crdoconnor12• 10 years ago

setup.py doesn't give a consistent mechanism to specify those kinds of dependencies.

daenney2• 10 years ago

How so? Any package in setup.py can declare a install_requires listing, including version matchers, of its (direct) dependencies. Those dependencies themselves should take care of listing theirs and so on completing the chain so that tools like pip can do their job.

That doesn't mean you can't run into a situation where a dependency cannot be resolved, but I don't see any problems around specifying them.

croon• 10 years ago

If pip can't find python-devel or a c compiler or whatever else, when it obviously knows that it's trying to run it, state that to the user and don't fail with "error 1".

0.02$ from a noob.

ubernostrum5• 10 years ago

Much of this article should be taken with many, many large grains of salt.

I've never run into a package that I needed to install which both A) had mandatory dependencies and B) refused to specify them in a way automated tools would understand and resolve. I'm sure there are packages out there which have this problem, because a dependency list is not mandatory in setup.py, but I've not had the experience of encountering such a package and I've been using Python for a living for over a decade now.

raverbashing• 10 years ago

1st problem, do pip install pip --upgrade in your virtualenv as the 1st thing. Another possible solution, install the corresponding .rpm/.deb package

2nd problem: go to this page first https://docs.python.org/3/py-modindex.html

3rd problem: yeah, kind of. Except for the logging module. Eff the logging module, it's a "java made in python" crap

talideon10• 10 years ago

Structlog FTW!

I only use the logging module these days when I've no alternative. The API for configuring logging is terrible.

gamesbrainiac• 10 years ago

I'd suggest using ZealDocs or Dash if you want fast searchable documentation.

sillysaurus3• 10 years ago

I think the Python docs are fine. I use them all the time. (The re docs in particular.)

It's not beginner-focused, but it'd suck if the current docs were replaced with docs for beginners.

The re page has over 7,000 words. I need those 7k words. They help me get things done.

Perhaps a solution might be something like a https://simple.docs.python.org type site: A simplified version, parallel to the existing documentation, consisting mostly of examples. I'd use it.

mrweasel• 10 years ago

The issue with the Python docs is that you have to ACTUALLY READ IT. Some language have documentation that you can just sort of skim and pick out the bits you think you need.

The Python documentation, and the Django documentation have additional information in the text. Describing how a module or function works, what you can expect and how you should use it. Important information is often "hidden" in the text and if you're the sort of person that doesn't actually read the documentation you're going to get it wrong.

The Python docs are absolutely fine, because actually tries to teach you how stuff works and why it is the way it is.

tgwallace• 10 years ago

I think the docs are often too verbose. Many pages start with a long winded intro that misses the main point. Some pages never get to the point. Docstrings are sometimes several pages long.

Example of not getting to the point: Extending/Embedding.

There is no fundamental difference. In both cases you're just calling a bunch of functions from libpython.a.

collyw• 10 years ago

I like Django docs. They are lacking information in some places but generally about right. Python's docs are the opposite, they have too much information. I just want to remember the calls for using a reqex with capturing groups, and its about 5 pages of text into the document.

falcolas2• 10 years ago

if you're the sort of person that doesn't actually read the documentation

Is this a problem with the documentation, or the reader?

Perhaps it's just me, but I can (and do) skim the Python library documentation regularly. Due to the high level nature of Python, any given bit of code is doing a lot of work under the covers. I'd rather that complexity is properly documented than glazed over in the official language documentation.

noufalibrahim• 10 years ago

This gap is very nicely filled by the Python Module of the Week series https://pymotw.com/3/ which focuses on examples rather than exhaustive docs. I believe the blog is coming out as a book called "Python standard library by example".

the_mitsuhiko2• 10 years ago

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.

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?

This schism in the community is causing more and more issues as time goes on.

Chris2048• 10 years ago

I'd like details on the "installing libraries" comment. for python, most distros come with a package, otherwise compilation is rarer.

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.

the_mitsuhiko2• 10 years ago

I'd like details on the "installing libraries" comment. for python, most distros come with a package, otherwise compilation is rarer.

Installing python modules from a system's package manager is not something people should do. It causes more issues than it solves.

majewsky2• 10 years ago

Can you go into more detail? So far, for my basic scripting needs, system packages have always been fine.

lqdc133• 10 years ago

People should do it in some cases because sometimes Python libs have to link against some other non-Python libs that are not part of the pip package.

Then if you just install the dependencies, sometimes the newer version in the PyPI requires a newer version of the dependencies, so you are stuck installing those things from source and building packages.

Steeeve• 10 years ago

This is not true with Gentoo. With debian, ubuntu, or rhel - the vendor provided packages are frequently out of date.

smcl• 10 years ago

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.

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 somewhere 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).

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 worse :(

thewhitetulip8• 10 years ago

build because of obscure compiler error

Exactly what I had in mind, I never got such problems at least in installing libraries, how can that be an issue since we have pip?

yes, some badly maintained libraries will have this, but that's the library author's issue and not a problem with Python's pip, on the contrary pip is working exactly fine if it complains.

edent2• 10 years ago

I tried installing OpenCV2. I needed to get Pip, then I tried to install OpenCV2, but it required a whole bunch of other stuff, which I had to compile, which failed.

Was a very frustrating afternoon.

vram222• 10 years ago

If on Windows, google Christoph Gohlke's (spelling?) big list of pre-compiled Python modules.

skvark• 10 years ago

Python's packaging system was and is still sometimes somewhat broken. However, it's getting better: compilation related issues are rarer nowadays thanks to the wheel pre-built package format (https://www.python.org/dev/peps/pep-0491/). Another great thing is the manylinux tag (https://www.python.org/dev/peps/pep-0513/) which allows to create portable packages which are compatible with many distributions + contain all required dependencies. For example, I didn't want to compile anymore OpenCV all the time by myself so I made it available as wheel package in PyPI: https://pypi.python.org/pypi/opencv-python

burntsushi• 10 years ago

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.

I maintain an open source Python project that tends to attract non-programmers or beginner programmers. This happens all the time. Case in point: https://github.com/BurntSushi/nfldb/issues/175

And that's a good case, because the error message is actually pretty nice compared to some others I've seen. But for a beginner user, learning to make the complete connection I wrote in my comment[1] on that thread is totally non-trivial.

[1] https://github.com/BurntSushi/nfldb/issues/175#issuecomment-...

Eridrus3• 10 years ago

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.

I've encountered this sort of thing plenty; usually it's not a python package that's required, it's a package you need to apt-get, and then another error pops up because that first one wasn't the only thing you needed.

gaius• 10 years ago

An odd article; the site is adware for a book, if the documentation was better he or she wouldn't have any sales!

gaur• 10 years ago

Has anyone made tldr pages for python packages?

afarrell2• 10 years ago

Is there a good place to go for critiques on your project's documentation?

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?

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.

faraggi• 10 years ago

I see many people like python docs, and I agree, but the article talks about the difficulty for __beginners__.

That being said, maybe the python docs need something equivalent of wikipedia's 'Simple English' definitions.

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.

Flimm2• 10 years ago

I don't think he's advocating for shortening the docs, if you look at the example he gave, his improved version was much longer: it explained each argument in detail as well as the return type, and gave an example.

hjnilsson• 10 years ago

The main problem with the python docs is not the verboseness. It's that they are entirely unstructured. If there just was a standard list of bold parameter - explanation and finally return value it would help immensely.

My own favorite is urllib.request.urlopen, the description mixes arguments, return values and exceptions in a blob of text two pages long. It's very confusing to read if you are a beginner just trying to fetch a file. The examples are way, way down on the page where you will never find them, the table of contents is so long you can't even see there is an example section unless you scroll down the menu.

On the bright side though, everything is explained in the text. It just less accessible than some other projects' documentation.

lkiux• 10 years ago

If python documentation is bad then, god forbid, these poor users should try to use anything else such as node.

As far as technical documentation does, the python documentation is usually ranging from pretty good to very good.

ap22213• 10 years ago

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.

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.

I can see why the docs are insufficient for today's beginners.

Eridrus3• 10 years ago

PHP is just as old and when I learnt PHP 14 years ago the docs were really friendly back then too, I loved being able to go to php.net/func_name and get a good description of how it worked. Of course this is for the standard library, which is what the article talks about, but PHP's standard library (at least then) had much more of the kitchen sink thrown in it.

willyt• 10 years ago

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.

talideon10• 10 years ago

I'm not sure if this is what you're looking for, but Sphinx, which is used for generating the Python docs, is capable of producing docs in a number of formats, including ePub and PDF, and offline versions of the docs have been available for download in those formats ever since the changeover to Sphinx: https://docs.python.org/3/download.html

partycoder2• 10 years ago

The typical narrative of the mediocre duct tape engineer.

"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."

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: https://docs.python.org/3/howto/regex.html

How did I find it? Google: regular expression site:python.org

iaskwhy3• 10 years ago

Is it really wrong to learn something new with examples and without having to read a full book before typing the first few lines of code? I prefer to learn by trial and error.

partycoder2• 10 years ago

It is a valid option to explore by trial and error. But once you have obtained something that seems to work, if you can't explain why it is working, it is a bad moment to stop.

If you construct an entire system by trial and error without an understanding of how and why it's working, you are exposing yourself and your customer to serious risks.

Even if things do not crash, if your code gets audited (e.g: when another person joins your team), you will have a bad time explaining your choices. As a professional engineer, it is expected of you to know what you are doing, and fudging code is the easiest way of getting sacked to the sound of a trumpet.

thewhitetulip8• 10 years ago

Installing libraries

I think pip and easy_install solves this problem. Or did I read the point incorrectly?

docs are horrible

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.

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

I love Go language's docs more though.

richardwhiuk• 10 years ago

Try "pip install pycurl". It'll fail. The solution is to install a C compiler and (on Ubuntu) run apt-get install libcurl4-openssl-dev. That's very different to other languages - they don't expect you to have a bunch of different development environments.

thewhitetulip8• 10 years ago

taking a quick look at the issue

the website says

PycURL is a Python interface to libcurl. and that would mean that we need libcurl installed. I am sure this is true with any other language as well, since this is a linker library, if that's a word.

also, surprisingly the website didn't mention that you need to install the libcurl4-openssl-dev :-)

so something is broken on this package.

Again, this is a package issue and not the issue of the language. We can find such examples in all languages. Doesn't mean Python's package system is broken or the language is broken.

I am waiting when the author will start teaching Go! just to read his "Problems everyone faces learning Go".

Illniyar2• 10 years ago

That's not really true, lots of languages requires certain modules to be built from source with a C compiler.

Ruby and Node.js comes to mind.

Though in general the community behind them do a much better job of hiding this complexity from the user - to the point that most times you don't realize you've compiled it from source.

anaphor• 10 years ago

Worked fine for me (I had never used it before). Perhaps the problem is with your OS? Learning how to install dependencies should be one of the first things a programmer learns. I don't think it's unreasonable to learn that a message like "Error: X requires this library! Failed to install" means you should go and install that library. Plus it can be frustrating when something comes with its own version of a certain library because it makes tracking down bugs more difficult. For example Python ships its own version of libffi (the library it uses to call C functions). I've had issues with this library before, and it turned out the Python devs hadn't bothered to update it in a long time, because it "worked", but it didn't for me, and the newer version worked fine. So I had to end up trying to rebuild Python from source with a more up-to-date version of libffi, which was a giant pain. It may be "easier" to make everything self-contained like that, but it causes headaches too. Maybe it would be better in those cases if the library were just packaged in the distro's package manager? (Or brew for Macs). That would allow for more complete dependency handling.

pbhjpbhj• 10 years ago

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.

I started with a Coursera course https://www.coursera.org/learn/python which was pretty easy (you can run the videos at 1.5 or 2x).

That course is based on a free gratis book by the lecturer (there a chapter on regex that covers re; with examples too).

I took a good few hours trying different IDEs and settled on PyCharm community edition, it has very easy doc lookup. (http://alicious.com/editors-ides-python-code/ is a brief summary of most of my IDE-for-python search.)

Currently I'm doing the Web Data course (using Beautiful Soup) and the only problem but is that by choice I'm using Python 3 when the course is written for 2. It covers regex pretty well.

mickmock• 10 years ago

I can't believe an advertisement has gotten so many up votes.

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

burnbabyburn• 10 years ago

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.

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.

Is there some good comment about python docs, packaging management, that isn't so much a rant?

vacri• 10 years ago

This being said, I find the PHP docs' styling to be easier to read. The python docs are all over the place.

This being said, the PHP doc linked to in the article is 15% document, and 85% user comments (why do docs even have user comments?). Yuck.

iaskwhy3• 10 years ago

While I understand the idea of not having user comments, back when I was doing php - and remember this was a time without StackOverflow - checking the docs user comments would get me going very quickly as some particular use cases would always show up there (and with improvements from other users too).

ForFreedom• 10 years ago

The trouble I had installing numpy, scipy and theano on python was over 3 days and only numpy & theano works.

3 days to go over the internet find out what the error... then trial and error.

Yes its difficult. And as the author says,"people get down voted"

oscii• 10 years ago

Regarding libraries, I often check unit tests for examples. But yeah, regex and similar docs suck.

stevetrewick• 10 years ago

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 guide and a language reference. 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!

For a complete 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 what you don't know.

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.

Edit: over opinionated autocorrect.

Cozumel• 10 years ago

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'!!

arximboldi• 10 years ago

You know what puts off beginners?

Articles plagued with stuff like "this is horrible", "this is shit" and so on and son.

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.

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.

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.

uola• 10 years ago

Many people have been and are contributing. But when there isn't critical mass or appreciation for changes they move on to other things. So the python community is not only left with the flaws but can't attract people to fix them.

Houshalter• 10 years ago

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!

https://news.ycombinator.com/item?id=11453086

avyfain• 10 years ago

Here's a cached version (thanks, Google!) since the site seems to be down: http://webcache.googleusercontent.com/search?q=cache:3GQ0z6z...

This Is What Python Beginners Have to Deal With

Related Stories