12 ms·

This Is What Python Beginners Have to Deal With

120 points by reubano 10y ago

devnonymous 10y 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.
- afarrell 10y 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 10y 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/ https://www.djangoproject.com/fundraising/ .
    - deleted 10y ago
      [deleted]
- em500 10y 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 10y 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?
junke 10y 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 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# 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.
- jacobolus 10y 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 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.
rtpg 10y 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 10y 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.
  - dkersten 10y 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.
crdoconnor 10y ago
1) is really something that the maintainers of pip should deal with but unfortunately they don't see it as their problem.
- talideon 10y 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.
  - dkersten 10y 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.
    - talideon 10y ago
      If everything's native[1], whether you're talking about Python, Java, or any other language, you're golden. The issue arises when you're calling out to something written in, say, C. You'll have the same pain in java if you start using JNI to call across the JVM boundary. It just crops up more in Python because C extensions get used a lot in Python. Addendum: [1] By this, I mean within the boundaries of the runtime environment and not using things like Python's C extension API or JNI. 'Native' is a poor choice of words.
adontz 10y 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?
- crdoconnor 10y ago
  setup.py doesn't give a consistent mechanism to specify those kinds of dependencies.
  - daenney 10y 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.
    - crdoconnor 10y ago
      How exactly is pillow supposed to specify in a standardized way that it depends upon libjpeg and that libjpeg-dev is supposed to be installed on debian based distros?
    - heartsucker 10y ago
      I think the author meant packages output of pip, like this issue: I want to install the pip package cryptography. I need to make sure Python.h is available. I need to make sure (on Debian) that lib-ffidev and lib-ssldev are available. This isn't said anywhere by pip (except Python.h, probably), and it's not the same on every system, let alone every Debian based system.
      - daenney 10y ago
        Ah, right, that makes sense. I don't think it's a fair criticism though, as you're crossing the boundaries between packages provided by your language ecosystem vs. those provided by your OS (distribution). There's no easy way to specify this in a way that would work on all platforms or you'd have to start adding logic to pip that knows how to apt/yum/pacman/port install those things. It's the same if you look at Ruby, Node, even Go and many others. The second you need native libraries/binaries all you have to go on is the hope that the author has documented them along with the rest of the installation instructions. The current only way around it is hoping that your distribution has packaged up the library you need (and is up to date enough for your requirements) in their native format and declaring the required dependencies.
raverbashing 10y 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 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
- talideon 10y ago
  Structlog FTW! I only use the logging module these days when I've no alternative. The API for configuring logging is terrible.
deleted 10y ago
[deleted]
gamesbrainiac 10y ago
I'd suggest using ZealDocs or Dash if you want fast searchable documentation.
ForFreedom 10y 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"
sillysaurus3 10y 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 https://simple.docs.python.org type site: A simplified version, parallel to the existing documentation, consisting mostly of examples. I'd use it.
- mrweasel 10y 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 10y 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 10y 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.
  - falcolas 10y 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.
the_mitsuhiko 10y 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 10y 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_mitsuhiko 10y 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.
  - majewsky 10y ago
    Can you go into more detail? So far, for my basic scripting needs, system packages have always been fine.
    - ubernostrum 10y ago
      First of all, distro packages essentially always lag behind the released upstream versions, so you have to begin with figuring out which version the distro packaged, and find documentation for that, include that version in all your questions to the mailing list for the library, and hope that you're not on a version so old that it's no longer supported upstream. Then there's the way distros like to make changes for "consistency" with the rest of their system. Command-line entry points get renamed or have options and behavior changed to reflect the distro's standards, but now the thing you're running isn't the thing upstream wrote or documented, so you're even more on your own if you hit trouble. Also, it's not unheard-of for distros to take something that's a single packaged entity upstream, and split it into multiple distro packages, possibly without making it entirely clear that to get full functionality you'll have to install multiple distro packages. And, again, this is specific to the distro and their choices, so of course upstream won't document it and may be just as baffled as you are when you ask why something that's important to you doesn't seem to be in the package you got. Finally, the Python ecosystem is built around the Python packaging and distribution toolchains. You're going to find plenty of expertise in things like using pip and virtual environments to develop and deploy Python, but all that goes out the window when you switch to using the distro package manager and packages. So you're giving up a lot of tooling built by and for Python engineers, for something which had to be a one-size-fits-all solution for the operating system it's bound to. So while you can do all right with system packages and tooling for quite a few use cases, the dangers aren't that far away and are ready to hurt you, badly, as soon as you stray just a little bit outside of what the distro optimized for, or need help with a package beyond what the distro and its packagers are able to provide.
smcl 10y 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 :(
- edent 10y 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.
  - vram22 10y ago
    If on Windows, google Christoph Gohlke's (spelling?) big list of pre-compiled Python modules.
    - edent 10y ago
      How do I know to do that? Most projects just say "Install OpenCV" or, if you're lucky, give you the step-by-step for doing a pip install. Assuming you already have pip.
      - Klathmon 10y ago
        I remember the first time I sat down to really do something with python, step 1 was setup a virtual environment... I never got to step 2 that week
gaius 10y 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 10y ago
Has anyone made tldr pages for python packages?
afarrell 10y 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 10y 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.
- Flimm 10y 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 10y 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 10y 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 10y 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.
- Eridrus 10y 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 10y 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.
- talideon 10y 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 https://docs.python.org/3/download.html
partycoder 10y 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 https://docs.python.org/3/howto/regex.html How did I find it? Google: regular expression site:python.org
- iaskwhy 10y 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.
  - partycoder 10y 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.
    - iaskwhy 10y ago
      Right but the article was about a beginner learning a new language, I don't think a beginner is expected to have audit-proof code for quite some time.
thewhitetulip 10y 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 10y 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.
  - thewhitetulip 10y 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".
    - nl 10y ago
      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. But this is just an example of the type of thing that is typical in Python using pip. Anaconda is a bit better (see [1] for the details) but it is a real problem. It isn't uncommon to resort to Docker to work around this. Pretending this isn't a problem for beginners (and even comparatively advanced users) isn't helpful. [1] https://www.continuum.io/blog/developer-blog/python-packages-and-environments-conda https://www.continuum.io/blog/developer-blog/python-packages...
pbhjpbhj 10y 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 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/ 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 10y 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 10y 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 10y 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.
  - iaskwhy 10y 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).
oscii 10y ago
Regarding libraries, I often check unit tests for examples. But yeah, regex and similar docs suck.
stevetrewick 10y 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 10y 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 10y 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 10y 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 10y 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 https://news.ycombinator.com/item?id=11453086
deleted 10y ago
[deleted]
avyfain 10y ago
Here's a cached version (thanks, Google!) since the site seems to be down: 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 http://webcache.googleusercontent.com/search?q=cache:3GQ0z6z...

120 points by reubano 10y 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.

afarrell 10y 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 10y 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/ https://www.djangoproject.com/fundraising/ .
  - deleted 10y ago
    [deleted]
em500 10y 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 10y 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?

junke 10y 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 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# 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.

jacobolus 10y 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 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.

rtpg 10y 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 10y 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.
- dkersten 10y 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.

crdoconnor 10y ago

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

talideon 10y 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.
- dkersten 10y 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.
  - talideon 10y ago
    If everything's native[1], whether you're talking about Python, Java, or any other language, you're golden. The issue arises when you're calling out to something written in, say, C. You'll have the same pain in java if you start using JNI to call across the JVM boundary. It just crops up more in Python because C extensions get used a lot in Python. Addendum: [1] By this, I mean within the boundaries of the runtime environment and not using things like Python's C extension API or JNI. 'Native' is a poor choice of words.

adontz 10y 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?

crdoconnor 10y ago
setup.py doesn't give a consistent mechanism to specify those kinds of dependencies.
- daenney 10y 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.
  - crdoconnor 10y ago
    How exactly is pillow supposed to specify in a standardized way that it depends upon libjpeg and that libjpeg-dev is supposed to be installed on debian based distros?
  - heartsucker 10y ago
    I think the author meant packages output of pip, like this issue: I want to install the pip package cryptography. I need to make sure Python.h is available. I need to make sure (on Debian) that lib-ffidev and lib-ssldev are available. This isn't said anywhere by pip (except Python.h, probably), and it's not the same on every system, let alone every Debian based system.
    - daenney 10y ago
      Ah, right, that makes sense. I don't think it's a fair criticism though, as you're crossing the boundaries between packages provided by your language ecosystem vs. those provided by your OS (distribution). There's no easy way to specify this in a way that would work on all platforms or you'd have to start adding logic to pip that knows how to apt/yum/pacman/port install those things. It's the same if you look at Ruby, Node, even Go and many others. The second you need native libraries/binaries all you have to go on is the hope that the author has documented them along with the rest of the installation instructions. The current only way around it is hoping that your distribution has packaged up the library you need (and is up to date enough for your requirements) in their native format and declaring the required dependencies.

raverbashing 10y 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 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

talideon 10y ago
Structlog FTW! I only use the logging module these days when I've no alternative. The API for configuring logging is terrible.

deleted 10y ago

[deleted]

gamesbrainiac 10y ago

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

ForFreedom 10y 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"

sillysaurus3 10y 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 https://simple.docs.python.org type site: A simplified version, parallel to the existing documentation, consisting mostly of examples. I'd use it.

mrweasel 10y 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 10y 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 10y 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.
- falcolas 10y 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.

the_mitsuhiko 10y 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 10y 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_mitsuhiko 10y 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.
- majewsky 10y ago
  Can you go into more detail? So far, for my basic scripting needs, system packages have always been fine.
  - ubernostrum 10y ago
    First of all, distro packages essentially always lag behind the released upstream versions, so you have to begin with figuring out which version the distro packaged, and find documentation for that, include that version in all your questions to the mailing list for the library, and hope that you're not on a version so old that it's no longer supported upstream. Then there's the way distros like to make changes for "consistency" with the rest of their system. Command-line entry points get renamed or have options and behavior changed to reflect the distro's standards, but now the thing you're running isn't the thing upstream wrote or documented, so you're even more on your own if you hit trouble. Also, it's not unheard-of for distros to take something that's a single packaged entity upstream, and split it into multiple distro packages, possibly without making it entirely clear that to get full functionality you'll have to install multiple distro packages. And, again, this is specific to the distro and their choices, so of course upstream won't document it and may be just as baffled as you are when you ask why something that's important to you doesn't seem to be in the package you got. Finally, the Python ecosystem is built around the Python packaging and distribution toolchains. You're going to find plenty of expertise in things like using pip and virtual environments to develop and deploy Python, but all that goes out the window when you switch to using the distro package manager and packages. So you're giving up a lot of tooling built by and for Python engineers, for something which had to be a one-size-fits-all solution for the operating system it's bound to. So while you can do all right with system packages and tooling for quite a few use cases, the dangers aren't that far away and are ready to hurt you, badly, as soon as you stray just a little bit outside of what the distro optimized for, or need help with a package beyond what the distro and its packagers are able to provide.

smcl 10y 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 :(

edent 10y 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.
- vram22 10y ago
  If on Windows, google Christoph Gohlke's (spelling?) big list of pre-compiled Python modules.
  - edent 10y ago
    How do I know to do that? Most projects just say "Install OpenCV" or, if you're lucky, give you the step-by-step for doing a pip install. Assuming you already have pip.
    - Klathmon 10y ago
      I remember the first time I sat down to really do something with python, step 1 was setup a virtual environment... I never got to step 2 that week

gaius 10y 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 10y ago

Has anyone made tldr pages for python packages?

afarrell 10y 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 10y 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.

Flimm 10y 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 10y 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 10y 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 10y 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.

Eridrus 10y 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 10y 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.

talideon 10y 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 https://docs.python.org/3/download.html

partycoder 10y 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 https://docs.python.org/3/howto/regex.html How did I find it? Google: regular expression site:python.org

iaskwhy 10y 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.
- partycoder 10y 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.
  - iaskwhy 10y ago
    Right but the article was about a beginner learning a new language, I don't think a beginner is expected to have audit-proof code for quite some time.

thewhitetulip 10y 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 10y 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.
- thewhitetulip 10y 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".
  - nl 10y ago
    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. But this is just an example of the type of thing that is typical in Python using pip. Anaconda is a bit better (see [1] for the details) but it is a real problem. It isn't uncommon to resort to Docker to work around this. Pretending this isn't a problem for beginners (and even comparatively advanced users) isn't helpful. [1] https://www.continuum.io/blog/developer-blog/python-packages-and-environments-conda https://www.continuum.io/blog/developer-blog/python-packages...

pbhjpbhj 10y 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 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/ 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 10y 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 10y 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 10y 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.
- iaskwhy 10y 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).

oscii 10y ago

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

stevetrewick 10y 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 10y 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 10y 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 10y 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 10y 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 https://news.ycombinator.com/item?id=11453086

deleted 10y ago

[deleted]

avyfain 10y ago

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