Well, in CodeIgniter's defense, its documentation was pretty excellent. The problem, however, was the slow and tedious development cycle, which favored backwards-compatibility over new features with almost no exceptions.

I came from Typo3 just to make it short it´s a big mess and only popular because some aspects are easy to sell (i guess).

Why is it that half of everyone says that PHP docs are so much better?

Because of the comment thread at the bottom of each function page... people paste in a common error and how to solve it. The docs are good not because they're written better (though in some cases they are) but because of the user contributed content which the python docs lack. I wish the python docs all has a disqus thread at the bottom.

Python docs have no clear indication what kind of parameters function takes, what values it returns and what happens when it fails:

http://docs.python.org/3/library/binascii.html#binascii.b2a_...

http://php.net/bin2hex

It clearly mentions that it returns a string and that data is binary data. As everywhere in python, when it fails, it raises an Exception.

Sure. Either it says it or it can be inferred from something. But it doesn't have a consistent format. When I'm checking unknown function in PHP I know exactly where to look for descriptions of behavior (also how it fails when it fails and why) and information about type or arguments and return values. And if I need real life use cases I can take a look at the bottom of the page.

In Python function description is often just unscannable short blob of prose.

Like for example http://www.php.net/manual/en/function.ming-keypress.php :P

edit: I feel like the real life examples in the PHP docs are very nice, but not really missing in Python (there are a lot examples in the Python documentation but not for such trivial functions). In python you just start the interactive interpreter and do "import module", "module.function(xyz)" and you see exactly what's going on. It's then a copy&paste away from your shell to your editor.

I'm not saying that PHP docs couldn't be better or more complete. Some (not only but usually less commonly used) modules are barely documented at all.

It's bit strange strange that you gave undocumented function as an example of how PHP functions are documented. :-)

This difference between Python docs and PHP docs is just the thing I noticed when I started having fun with Python which is btw awesome language though finding which lib to use for given task sometimes is hard.

Good thing to do to find out what python function does is running help(module_name.function_name) in interpreter.

I'd say both documentations are very complete but take a different approach. Very often the python standard library is very self-descriptive and it's just doing what you would expect. If you're in doubt you can always start up bpython and have an autocompleted shell. That python has an interactive interpreter really is very convenient.