Python documentation too difficult for beginners

[Tim Harig]

On 2010-11-02, jk <sanjo_ie at yahoo.com> wrote:
> As for the 9 paragraphs statement, there's a usability book that
> applies here - it's called "Don't make me think". I shouldn't have to

Anything that promotes a lack of thinking sends up red flags in my head.
We want to recruit smart people who think, not idiots.

> go through freeform text to find what I'm looking for when a list
> would make that information easier to find. And splitting the docs
> into sections would allow me to skip to what I'm looking for. I really
> would be much happier with your example documentation.

ctrl-f will bring up a search dialog in most graphical browsers.  '/' will
in many others.  With some practice, your fingers will be able to find
something far faster then your eyes can see it happen.

There is a religious war in the GNU community between info page as
documentation versus the traditional manual format.  The manual format
contains all of the information on one page that can be easily searched
whereas the info pages are split into sections that must be viewed
individually.  With the man pages, you can almost always find what you want
with a quick search through the document.  Info pages are much harder to
use because you have to try and figure out which section the author decided
to place the information that you are looking for.  The information may be
stored several levels deep, which means that it can be a deep productivity
hit if you don't guess the proper location on the first try.

> I think the key difference is that I don't want to have to *read* the
> python docs - I want to be able to scan for what I'm looking for and
> find it easily. That makes me productive.

The real question is what do you want to gain by your posts here.  You
should already know that most groups are, by their very nature, slow to
make changes to the status quo.  The problem tends to be exasperated in
open source projects where any changes mean that people have to donate
their time to make anything happen.  You will in general find two things to
be true:

1. Since they are dontating their time, you will find that people tend to
	scratch their own iches first.

2. People who do take the time to contribute to open source projects are
	people of action.  They don't tend to be appreciative of those who
	constantly generate feature requests but have no inclination to do
	any of the work themselves.  They do appreciate other people of
	action who are interested in making the project better.

Therefore, if you truly want changes in the documentation, I suggest that,
rather then whining to the group, you make some of the changes yourself.
When you are finished, you can post a link to your alternate documentation
to this group.  If you documentation is truly better then the existing
documentation, you will not have to say another word.  People within the
community will rally around it and promote it.  If it gains wide enough
support, then there will be a movement to use it to supplant the existing
documentation.  It is the difference between whining from the sidelines and
actively participating in the game.