[docs] python tutorial more a reference than a tutorial

[Amandeep Singh (amandsin)]

I can try to point to some pages where I struggled.

Section 9.2 of classes is very tough to read. 

In Chapter 7, Section 7.1, first line says,

"So far we've encountered two ways of writing values: expression statements and the print statement".
I tried to figure out what expression statements were. Went to the index page, found nothing. You might have given definition somewhere else, but just giving an example here could have made the context much simpler.


-----Original Message-----
From: Éric Araujo [mailto:merwok at netwok.org] 
Sent: Wednesday, July 28, 2010 8:58 PM
To: Amandeep Singh (amandsin)
Cc: docs at python.org
Subject: Re: [docs] python tutorial more a reference than a tutorial

Hello Amandeep

Thank you for your feedback.

>> I tried to study your python tutorial, release 2.6.4. But was very
>> disappointed the way it is written. It is more a reference than a
>> tutorial. Language could have been simpler, giving more examples.

Can you point out examples of complicated language, or maybe give links
to other tutorials that have been better for you so that we can compare?

I remember that Dive Into Python was the accessible thing for me when I
started learning Python, the official tutorial came after. The first two
chapters (“Whetting Your Appetite” and “Using the Python Interpreter”)
can certainly be off-putting for someone with no prior programming
experience.

Other tutorials may favor a hands-on approach, i.e. starting with a
project and going ahead, which is a very good way to learn. The official
tutorial seems more traditionally structured and less accessible; maybe
there’s room for a new, shorter, practical one (written from scratch or
copied from an external source).

[Anatoly]
> Loss of consistency is always a problem with documentation that is
> maintained in patches.

The documentation is files; editions are made with patches, like
everything else. What is the consistency problem? That people review the
patches and not the whole files maybe? I believe that there are readers
that catch consistency problems while reading the built doc, and I trust
Georg not to commit inconsistent changes.

> The whole Python documentation lacks user submitted scenarios and
> examples.

What are user-submitted scenarios? How are they useful?

Regarding examples, the doc of some modules is already so long that
there is need for a summary table, see for example itertools (other
modules would benefit from that). I don’t know if python-dev explicitly
wants the documentation to stay focused or if more examples are welcome;
at least, links to more detailed resources like
http://www.doughellmann.com/PyMOTW/ and
http://code.activestate.com/recipes/langs/python/ would be a useful
addition.

> I sell this idea for PSF for free. Take a look at online pages at
> http://php.net/ for an inspiration.

This doc has already been mentioned as example on mailing lists, only to
be shot down by other PHP users criticizing the low quality and
staleness of those user-submitted examples.

That said, there is a constant effort to lower the bar for
contributions. There has recently been changes to advertise this mailing
list and the bug tracker more prominently; what more can we do?

Regards