Python Documentation (vs PHP stuff)

[Roel Schroeven]

Terry Reedy wrote:

> Because of these two posts (and a few others) extolling the PHP 
> documentation, I decided to take a look for myself to see what the 
> fuss was about and whether I could get any ideas on how to improve 
> Python's docs.
> 
> [...]
> 
> Finally, 80% of the chapter/page consists of a thrown-together 
> mish-mash of unsorted. unedited comments and questions.

In my experience, the user comments in many cases are almost useless.
Sometimes just confusing, sometimes contradicting each other, sometimes
even incorrect. Sometimes correct and useful too, but IMO that gets
drown between all the others.

> [...]
> Sorry, PHP doc fans: to me, this sort of  inflated, noisey bloatware
> is wretched, not outstanding.

Thank you. I thought I was the only one in the world who doesn't like
the PHP documentation.

> Conclusion 1: if PHP is anything as awful as the manual, it is not 
> for me.

I'm fairly sure you won't like PHP :)

Some time ago I used to do some programming in PHP on the side. In the 
beginning, I thought PHP was quite a nice language. I even used it to 
write some small non-web programs that I would otherwise haven written 
in C or C++ (I didn't know Python at the time, nor any other decent 
scripting language(*) ).
Then I discovered Python, which caused my dislike of PHP to grow even 
more. PHP tries to make everything as simple as possible but that 
doesn't always work out very well, as explained in the section 
'Oversimplification Leading to Excessive Complexity' of this paper:
http://www.ukuug.org/events/linux2002/papers/html/php/#section_5.
Python OTOH makes things as simple as possible but not any simpler, and 
that turns out to work much better.

(Disclaimer: I haven't done any web programming in the meantime, so I 
don't know from own experience how Python fares in that area. But I'm 
fairly confident that it would work out just nice.)


(Sorry for this off-topic rant)

(*) I know Python is not just a scripting language, but the things I 
used PHP for at the time really were nothing more than scripts, despite 
me thinking about writing them in C or C++.

-- 
If I have been able to see further, it was only because I stood
on the shoulders of giants.  -- Isaac Newton

Roel Schroeven