[PyQt] Howto use the Qt documentation successfully

[Robert Lummis]

I'd like to second Peter Milliken's sentiments. The PyQt documentation
that's available is (in my opinion) pretty poor. Finding a way to do
something that you haven't done before by browsing the documentation
is nearly impossible. Or at least it's so frustrating and
time-consuming that I often give up before finding what I need. The
only way I've successfully implemented something is by starting with a
working example I find by googling or in Mark Summerfield's book and
vary it to suit my needs. That's not an ok method for serious
programming.

To be more concrete, I think there are at least two main shortcomings.
1)  good meta-documentation isn't available. (Or, if it is available,
I haven't found it.) One part of the meta-documentation would guide
you to the classes, procedures, etc. you should read based on the
tasks you want to accomplish, and say which classes "go together".  It
would contain indexed annotations on the existing pages so, for
example, if I want to program a way to edit fields in a database I
could look in its index under "fields" or "database" or "edit" and I
would be taken to a listing of all the relevant classes (not just the
ones with those words on their pages) with annotations about what each
does. Or if I want to control an external device I would find an
annotated listing of the classes that might be applicable.  This would
have to be written by hand, not generated by a program. 2) The
existing documentation itself, while extensive and obviously the
result of a huge effort, is still not good enough. For one thing it
assumes knowledge of C++. That is lame because a key advantage of PyQt
is that you can be productive without knowing C++. Also, many of the
pages have missing information, such as the list of arguments for a
class, and/or have missing or broken links, or the explanations refer
to arguments by name and the names don't match the names in the class
heading. All of these taken together, along with other shortcomings
I'm not mentioning, add up to a major barrier to learning. I guess if
you already know a lot of PyQt the documentation seems good because it
lets you look up some detail you didn't memorize. But it isn't very
helpful to potential users who don't know a lot yet.

I hope nobody takes these comments as personal criticisms because they
aren't meant as such. I am in awe at the talents, dedication, and hard
work by the Qt and PyQt developers and the gurus on this list who are
putting so much time into supporting PyQt users and learners. I'm
trying to be constructive by giving feedback from a typical learner,
and possibly spark a new effort to improve the documentation. I want
to learn to use PyQt and I'm willing to put a lot of time into it, but
the state of the documentation makes it unnecessarily hard. I haven't
given up yet but I'm pretty discouraged.

If I'm wrong about what is lacking, which I may be, I hope someone
will (tactfully) enlighten me. However, even if I'm wrong my
frustration is an indication that everything isn't what it should be.
-- 
Robert Lummis