Comment by crazygringo | Hacker News Reader

Comment by crazygringo | Hacker News Reader

Parent Full thread

I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run.

But it seems like there's a big trend now to just "get things out there" and that good documentation isn't "cool" anymore, kind of like braces in syntax.

Examples of good docs: PHP, jQuery, MySQL. (The first two sites include user comments too, which make things even more useful.)

Examples of terrible docs: Python, CoffeeScript (the worst)

I can at least understand insufficient docs for pre-1.0 versions when the implementation is changing constantly, but when something has been around for more than a year, it's just inexcusable.

I don't want a "getting started" guide that gives a bunch of examples. I don't want to type in the console to find out what methods an object has.

I want a friggin' reference manual, that includes (as applicable) syntax rules, exact rules governing whitespace, orders of operations, all functions, all parameters, parameters passed to a callback (why are these forgotten so often?), default values, flag values, all possible return values, specific exceptions that can be thrown, what input parameters result in undefined behavior.

Really, it's just not that hard. It may be grunt work, but if you'd rather make your users waste a cumulative 25,000+ hours figuring things out, rather than you spending 100 hours of your own explaining things, I just can't have respect for your product, no matter how otherwise amazing it is.

Why is the Python documentation terrible in this respect? Python comes with a language reference[1], that has most of the components you ask for (one of the components is in a document that's called something other than the language reference, but that's because it's the stdlib, not the language itself... it's certainly the same style of document, not a tutorial!):

1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)

2. Whitespace (section 2.1)

3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)

4. All functions, types, classes... both globals and stdlib modules are documented in http://docs.python.org/library/index.html#library-index

5. All parameters? Documentation should already have these.

6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented

7. Default values and their meanings are pretty much always documented

8. I don't know what flag values are, but if they're just parameters they fall under (5)

9. Return values and exceptions should always be documented

10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.

[1] http://docs.python.org/reference/

I program in Ruby most days.

A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed.

So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python libraries. There didn't appear to be the equivalent of RubyGems or Bundler. There did seem to be 2-3 different ways of managing them (eggs?), but just getting those programs working on my local system wasn't liking me either. Googling for "Using Python libraries" didn't return much useful- nor did "Installing Python Libraries".

I'm still unclear what the standard method for managing these is. When I checkout a Ruby thing, I just type 'bundle install' and all is fine then.

Yes, the technical docs were fine- but the baseline "how do I get this damn stuff, working!?!?!" wasn't.

> I'm still unclear what the standard method for managing these is.

If only this was just a documentation issue. Alas, the reason is that there is no standard method. Here's a short practical article on how to install Python packages and get on with your life: http://dubroy.com/blog/so-you-want-to-install-a-python-packa.... For a longer historical perspective of this whole clusterfuck check out http://lucumr.pocoo.org/2012/6/22/hate-hate-hate-everywhere/

There are various methods for installing 3rd party python libraries from PyPI [1], including easy_install, pip, or just extracting the tarball from PyPI and running `python setup install`.

1: http://pypi.python.org/pypi

Edit: There's also the official documentation page called "Installing Python Modules" which covers the last of those three methods: http://docs.python.org/install/index.html

Edit 2: and from the FAQs, http://docs.python.org/faq/library.html#general-library-ques...

Package installation is a known pain point in python. The problem is one of a plethora of half-baked solutions.

For now, you can get most of the way by trying 'pip install X' or 'easy_install X', but there are important edge cases.

It's being worked on for Python 3's next big release, last I heard.

I think this might be an issue with what you're used to. We have things like rvm, gems and bundler: look at virtualenv, distutils/setuptools... The equivalent of a Gemfile is a requirements file, pip knows how to install these (pip install -r FILE).

If you ask me to do the same in Ruby, I'd probably be lost too.

You mention CoffeeScript being one of the worst, and I don't necessarily disagree, but how has it become so popular despite its poor documentation? Is it because CS is just /that/ good? Or is it that it has developed a great community early on that compensates for the lack of documentation? Either way, writing good documentation seems like an either path than doing those two things.

There's also a third reason: it's very easy to see what CoffeeScript compiles to - the JavaScript source is easy enough to read and comprehend - and that behaviour is well documented.

Most of the times I'm looking at CoffeeScript to just figure out what it compiles to!

I don't see why you say that Python docs are terrible while PHP docs are good. Can you provide details? Are you sure this isn't just a matter of liking certain conventions over others?

It's a recurring argument on HN whether Python docs are good. Someone claims they're terrible, and someone always asks, "Why? I think the docs are good!"

There's a critical gap between the expectations of Ruby/Java programmers of how to write Python and the way Python programmers behave. I think it really is cultural, to an extent. The Java programmers look for Java-style documentation, with classes and methods and lists of exceptional conditions. The Ruby programmers look for Ruby-style documentation, with lots of diversions into the "why" of things and the context, possibly with pictures of foxes.

A Python programmer would consider the Java docs needlessly detailed and the Ruby docs a bit fluffy and not to the point, but after all, it is just a matter of viewpoint, community goals, and culture. There's also the issue of installing packages in Python, which can be a bit of a bummer, but I've never had a problem downloading a Python package from some site and following the directions.

What do you reproach to python and coffeescript docs? I find them very good and very usable. I want to do something? I have the answer nearly immediately (well except for some shitty modules in python (I'm looking at you urllib(2)/popen)) and it's a real pleasure to use them while coding.

Python docs may not be exactly beginner friendly, but it's certainly not terrible.

I agree 95%. However, I really do like to see a lot of simple examples. They can often make things much easier to understand once you see it. Similar in concept to "A picture is worth a thousand words".

I don't see how Python docs are terrible. Any doc is a help() away from you on any REPL.

You're in a small minority, what you want and don't want is irrelevant. It's 2012, nobody reads dry reference manuals cover to cover, nevermind doing so before firing up a shell window and an editor.

Reference manuals are still nice to have of course for clarifying edge cases and solving language lawyer disputes. However claiming that they are a superior learning and time-saving tool than the learn-by-example techniques is way out of touch with how most people actually learn.

People learn in a variety of different ways, and I'm also a developer who always prefers a reference manual over learn-by-example techniques. You may not be one of those developers, but that doesn't mean we don't exist. I imagine there are plenty of people who don't learn by the reference manual but would prefer to have it available - if it was available - as well.

"It's 2012, nobody reads dry reference manuals cover to cover" speak for yourself and stop making sweeping assumptions when you actually have no clue.

I don't read them cover to cover, but I need info on specific subjects quite often, and some tools just don't have it.

People in the hardware or embedded system industry have to read it page by page, word by word because they do. People who actually design compilers have that too. People who actually work with specs like Mozilla have a big manual too. People who actually use a 3rd-party product and integrate them into their product have to read those manuals a hundred times including meeting with the vendor.

If you are only doing your own product using Python libraries, then certainly you don't.

Reply on news.ycombinator.com