wxPython documentation

[Josiah Carlson]

> If C++ docs are "easy" to convert in your head to Python.
> It does help if YOU KNOW how to program C++ first.
> So much for learning Python as a first computer language!
> And if you have to learn C++ first, then why do you need Python?

Spend a few hours learning C++ syntax.  It is easy.  And you'll then be 
able to use all the 'hard' documentation that you couldn't before.

The reasons that people use Python, as opposed to C++, are varied and 
nontrivial.  If you don't know the reasons why /you/ use Python as 
opposed to other languages, then why don't you give C++, Java, Scheme, 
etc., a shot.  If you find that they float your boat better than Python, 
then use them.  No one is forcing you to use Python.  No one is forcing 
you to use wxPython or PyGTK or PyQT.  But understand that sometimes you 
will need to /learn/ in order to use.


> Why do all programmers seem to think good documention is optional?
> Or an exercise left to the reader?

The wxWindows documentation is fairly optimal for C++ programmers.  It 
is tolerable for Python programmers.  Why?  Because a large portion of 
Python programmers knew C/C++ before finding Python, and it is an easy 
translation.  Those people that only know Python are limiting themselves 
intellectually.  Learning other languages and methodologies will allow 
them to understand the context of Python, and in the case of learning 
C++, will allow them to use documentation that they couldn't before.

The fact is, C++ function calls are self-documenting, where each 
argument tells you what its type is:

wxButton(wxWindow* parent, wxWindowID id, const wxString& label, const 
wxPoint& pos, const wxSize& size = wxDefaultSize, long style = 0, const 
wxValidator& validator, const wxString& name = "button")

It is relatively easy for someone who knows the general syntax of C++ to 
have no problems using the same documentation.  And as I said earlier, 
learning general C++ syntax is easy.  Heck, if hundreds of thousands of 
undergraduate computer science majors can do it between ~1990 and ~1999, 
then you (and everyone else) can too.


> Documentation quality tells a lot about the programmer.
> If a programmer can't communicate to his users how his program works.
> It is a warning sign that the program has not been fully designed, but
> hacked together haphazardly.

Ahh, but as I said earlier, wxWindows C++ documentation is high quality. 
  Translating everything from C++ to Python would take a shitload of 
time, and wouldn't necessarily gain anything.  'Fixing' the above call 
would result in:

wxButton(parent, id, label, pos = wxDefaultPosition, size = 
wxDefaultSize, style = 0, validator = None, name = "button")

But how has the call been simplified?  Now we need to spend 20 lines 
telling people exactly what types of things need to be passed, where the 
original C++ documentation did just fine.


Furthermore, wxWindows people wrote the documentation for C++ 
developers.  The group of people wrapping wxWindows calls for Python 
have no reason to spend their time 'fixing' the hundreds of pages of 
documentation, when a resonably intelligent Python programmer should be 
able to spend an hour learning general C++ syntax, and have no problems 
understanding the wxWindows documentation.

It is not a matter of poor design, or poor-quality software, it is a 
matter of; it is already documented in a reasonable format.  Those who 
don't find the format reasonable, have limited programming experience in 
the first place, are not self-motivated enough to learn the syntax, and 
no amount of documentation will help them.


Hell, take for example the 10 posts in the last couple weeks about, "how 
do I start up an external program from Python, I've looked at the 
documentation, but it isn't possible".  There are no less than 22 calls 
that allow you to start an external program, all fully documented. 
Apparently they haven't spent 5 minutes reading through the os module.

> Say, like on the Spirit Mars Rover.

It is working now.  They fixed it.  I'd say that the ability to write 
software that can recover from failures is an example of good software, 
not bad.

  - Josiah