How to use wxPython documentation

wxPython Users
21

Hi All,

David Lyon wrote:

Let's fix this...

Well, I'd like to use the term "improve" rather than "fix", but yes, your
points are well taken. However, one of the big issues is that docs take a
lot of work, and it's not fun for coders, and it doesn't help anyone that is
writing the code actually solve a problem.

Also, docs that are not up to date are worse than hard to navigate docs, so
it would be really, really good if the core docs were essentially
auto-generated from the source. That's what the "new" wxPython docs are.
That was an effort Robin put in a couple years ago that has stalled --
picking up on it to get the results cleaner and neater and more easily
searchable would be great.

Andrea put some work into this recently, and that spawned a discussion on
this list, but I don't know that it lead anywhere.

The docs I generated are Sphinx-based, like the scipy/numpy ones. I
have removed all the C++-ism (or almost all of them). There was some
discussion in the past but it looks like we will follow the doxygen
approach in the future documentation. My only remark was that if we
could put the docstrings in the Python files, we could use Sphinx to
do all the work for us and generate docs which are nicer and more
intelligent than the default ones. As far as I understand, there
should be this possibility using some modified SWIG routine Robin has
put together, but I don't really know the status of this.

I am willing to investigate more if there is any interest, especially
if the new documentation comes out.

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/

···

On Wed, Mar 11, 2009 at 5:29 AM, Christopher Barker wrote:

22

David,

David Lyon wrote:

…


3) on the F1 key in Boa Constructor (Help key)
Something simple like that..

F1 in Boa:

moz-screenshot-105.jpg
moz-screenshot-105.jpg434×282 23.1 KB

Something like this,
although I still prefer ctrl-h as it gets me where I really want to go
to.
With a bit of work you can add documentation of other packages (if they
can be created as help books).
David, as you can see we are all very defensive when you “attack”
wxPython.
I think I know that you don’t attack it but would like to help in
making it even better.
I am sure there was some effort in helping to complete the new API
wxPython documentation, but I can’t find it, hopefully Robin will chip
in.
Werner

···

:slight_smile:

:slight_smile:

23

David,

David Lyon wrote:

...

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation
  

There was some discussion going on using Sphinx (see Andrea's version: http://xoomer.virgilio.it/infinity77/wxPython/) to generate the documentation - but I do not know what the final outcome/decision was.

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

Werner

24

Hi Werner & All,

David,

David Lyon wrote:

...

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation

There was some discussion going on using Sphinx (see Andrea's version:
http://xoomer.virgilio.it/infinity77/wxPython/) to generate the
documentation - but I do not know what the final outcome/decision was.

The little I know about Sphinx is that it should allow for having code
examples in the doc - maybe this could even be linked in/to the wxPython
demo as the source for the code examples?

There already are some example of code in my version of the
documentation, see for example:

http://xoomer.virgilio.it/infinity77/wxPython/animate/wx.animate.html
http://xoomer.virgilio.it/infinity77/wxPython/grid/wx.grid.html
http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.CollapsiblePane.html

And many more...

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/

···

On Wed, Mar 11, 2009 at 10:23 AM, Werner F. Bruhin wrote:

25

Andrea,

Andrea Gavana wrote:

Hi Werner & All,

David,

David Lyon wrote:

...
    

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation
      

There was some discussion going on using Sphinx (see Andrea's version:
http://xoomer.virgilio.it/infinity77/wxPython/) to generate the
documentation - but I do not know what the final outcome/decision was.

The little I know about Sphinx is that it should allow for having code
examples in the doc - maybe this could even be linked in/to the wxPython
demo as the source for the code examples?
    
There already are some example of code in my version of the
documentation, see for example:

http://xoomer.virgilio.it/infinity77/wxPython/animate/wx.animate.html
http://xoomer.virgilio.it/infinity77/wxPython/grid/wx.grid.html
http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.CollapsiblePane.html
  

Could the code sample come from the wxPython demo instead of having it within the .rst file? Looking at the source it looks like it is directly from the .rst file.

I also like the Control Appearance stuff directly in the doc.

Werner

···

On Wed, Mar 11, 2009 at 10:23 AM, Werner F. Bruhin wrote:

26

Hi Werner & All,

Andrea,

Andrea Gavana wrote:

There already are some example of code in my version of the
documentation, see for example:

http://xoomer.virgilio.it/infinity77/wxPython/animate/wx.animate.html
http://xoomer.virgilio.it/infinity77/wxPython/grid/wx.grid.html

http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.CollapsiblePane.html

Could the code sample come from the wxPython demo instead of having it
within the .rst file? Looking at the source it looks like it is directly
from the .rst file.

This is because the way the old wxPython documentation was. But if you
can include the sample code in the docstrings, Sphinx will do
everything by itself. Example:

def MyMethod(self, dc, rect):
""""
Some useful docstrings.

**Parameters:**
* `dc`: the client dc
* `rect`: the window rect

Example::

self.MyMethod(dc, rect)
self.DrawSomething(dc)
"""

Notice the 2 ":" after the word "Example". The 2 ":" tell Sphinx that
what follows is Python code and it will automagically output the
sample in the docs. It's not that hard to parse the wxPython demo and
include the samples we want in the docstrings.

I also like the Control Appearance stuff directly in the doc.

Yes, this is a big plus if we can generate enough "Control
Appearances" for almost all the widgets on all platforms.

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/

···

On Wed, Mar 11, 2009 at 12:20 PM, Werner F. Bruhin wrote:

27

David Lyon wrote:

Hi,

Can I make a comment?

Is it just me or does anybody else find the wxPython Documentation
unsatisfactory?

I came from using Delphi, and the VCL is extremely consistant and well
documented.

Where would I go if I wanted to help with a revamp the wxpython
documentation?

I'm hoping something can be done about it and might have some time to spare
to do it.

David
  
I started with the wxPython book by Robin Dunn and Rappin. When I wanted to learn about the widgets, I used the demo which includes a wxWidgets help file. I usually use the book + the demo for most things, then Google and the mailing list is my last resort. I usually can't find what I want in the wiki, but it has been helpful from time to time or just for extracurricular learning purposes.

Yes, the docs are kind of sucky since they're auto-generated. I know Robin accepts documentation submissions, but I don't know the format.

···

-------------------
Mike Driscoll

Blog: http://blog.pythonlibrary.org

28

David Lyon wrote:

For developers coming from other environments that are more
cleanly laid out.... it comes across as being very disjointed
and messy.

Code examples are my biggest issue on the class reference..

There appear to be none...
  
Yes, there are, they just aren't embedded in the doc. The example are
in the separate demo application, an incredible resource that I have
never found in other open source projects.

In Delphi and VB and every other language you got a code example of how to
use a method/function... you didn't need to go off to a search engine and
look for 10 minutes each time to see how to actually do something.
  
Delphi and VB are products that cost a thousand dollars or more, backed
by huge multinational corporations with large professional programming
and technical writing teams, funded by all of those customer product
purchases. Wx has no such thing. wxPython, in particular, is a product
that is owned and managed by essentially one person. Robin would assert
that this is an exaggeration, but it's not far off. If you want the
documentation to be better, then by all means please MAKE it better and
submit your results. That's how open source products improve.

One of the difficulties with documentation for a product like this is
that everyone learns differently. For me, I learn best by example. By
far, the best reference source for me is the huge wxPython demo
application, which has an example usage of virtually every feature in
the toolkit. I do refer back to the wxWidgets C++ reference material,
and that does require a certain amount of mental translation. Again,
for me, that's not a big deal.

This is the biggest frustration for any new user....
  
Not so. It is quite possibly the biggest frustration for YOU, but
everyone learns differently.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
  
I'm not sure that's a productive use of time. wxPython is a relatively
thin mapping of the C++ wxWidgets library. The core feature development
happens in the much larger wxWidgets team, and they're the ones who
document that core development, in C++ terms. It's not necessarily
productive to rewrite all of the arcana in that documentation. I agree
that the documents should describe where wxPython differs, and for the
most part, it already does so.

3) Get all the main classes (~50), properly documented
4) Get code examples for #3
  
There ARE code examples, in the demo app. They just aren't embedded in
the documentation. Have you ever done any technical writing? It is
very difficult to overestimate the incredible amount of time and effort
this requires, and for now most of would rather that the people who CAN
invest that time effort remain focused on programming.

and all will be good/better
  
...in your opinion.

···

--
Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc.

29

Werner F. Bruhin wrote:

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

That would be great -- also maybe links to the Wiki, though Wiki's are a bit ephemeral for that. I suppose we could have a Wiki page for each wx class -- then folks could add to them as we go. But maybe that level of docs really belongs in the main docs anyway, and we can save the Wiki for larger topics/examples.

I have close to 100 little demos that I've developed over the years to test various controls and methods. I'd like to put them somewhere, but haven't found any easy place to put them that would be organized enough to be useful, and easy for me to do. Anyone have any ideas?

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

30

For what it's worth, Tim, although I think that improving the docs in the
ways that Andrea, Chris, David, and others are discussing is a good
idea, I found this a pretty compelling rejoinder, and very well-put.

That said, if people could do it, I would be excited to see a docs that
combines the features that Andrea is talking about and has already done,
and then having that linked through the wxPython site.

By the way, maybe a tall order, but could there any easy-ish way for
people to annotate the docs to provide links to relevant email discussions,
as with a wiki? Yes, there is Google, but real human semantic intelligence
still beats that (at least for now).

And Tim's point about the C++ version being not much different from the
Python one is true, but it seems like it must be at least somewhat off-putting
to people just learning Python/wxPython/programming from scratch. This was
my experience, at least. That the wxPython site currently links to the C++
version is probably something that might get sorted out if people work on this
issue.

Che

···

On Wed, Mar 11, 2009 at 12:55 PM, Tim Roberts <timr@probo.com> wrote:

David Lyon wrote:

For developers coming from other environments that are more
cleanly laid out.... it comes across as being very disjointed
and messy.

Code examples are my biggest issue on the class reference..

There appear to be none...

Yes, there are, they just aren't embedded in the doc. The example are
in the separate demo application, an incredible resource that I have
never found in other open source projects.

In Delphi and VB and every other language you got a code example of how to
use a method/function... you didn't need to go off to a search engine and
look for 10 minutes each time to see how to actually do something.

Delphi and VB are products that cost a thousand dollars or more, backed
by huge multinational corporations with large professional programming
and technical writing teams, funded by all of those customer product
purchases. Wx has no such thing. wxPython, in particular, is a product
that is owned and managed by essentially one person. Robin would assert
that this is an exaggeration, but it's not far off. If you want the
documentation to be better, then by all means please MAKE it better and
submit your results. That's how open source products improve.

One of the difficulties with documentation for a product like this is
that everyone learns differently. For me, I learn best by example. By
far, the best reference source for me is the huge wxPython demo
application, which has an example usage of virtually every feature in
the toolkit. I do refer back to the wxWidgets C++ reference material,
and that does require a certain amount of mental translation. Again,
for me, that's not a big deal.

This is the biggest frustration for any new user....

Not so. It is quite possibly the biggest frustration for YOU, but
everyone learns differently.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation

I'm not sure that's a productive use of time. wxPython is a relatively
thin mapping of the C++ wxWidgets library. The core feature development
happens in the much larger wxWidgets team, and they're the ones who
document that core development, in C++ terms. It's not necessarily
productive to rewrite all of the arcana in that documentation. I agree
that the documents should describe where wxPython differs, and for the
most part, it already does so.

3) Get all the main classes (~50), properly documented
4) Get code examples for #3

There ARE code examples, in the demo app. They just aren't embedded in
the documentation. Have you ever done any technical writing? It is
very difficult to overestimate the incredible amount of time and effort
this requires, and for now most of would rather that the people who CAN
invest that time effort remain focused on programming.

and all will be good/better

...in your opinion.

--
Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc.

_______________________________________________
wxpython-users mailing list
wxpython-users@lists.wxwidgets.org
http://lists.wxwidgets.org/mailman/listinfo/wxpython-users

31

Christopher Barker wrote:

Werner F. Bruhin wrote:

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

That would be great -- also maybe links to the Wiki, though Wiki's are a bit ephemeral for that. I suppose we could have a Wiki page for each wx class -- then folks could add to them as we go. But maybe that level of docs really belongs in the main docs anyway, and we can save the Wiki for larger topics/examples.

I have close to 100 little demos that I've developed over the years to test various controls and methods. I'd like to put them somewhere, but haven't found any easy place to put them that would be organized enough to be useful, and easy for me to do. Anyone have any ideas?

-Chris

Google code? Launchpad? I could help you stick them on the wiki too, if we split them up.

Mike

32

Hi Werner,

David,

David Lyon wrote:

...

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation

There was some discussion going on using Sphinx (see Andrea's version: http://xoomer.virgilio.it/infinity77/wxPython/) to generate the documentation - but I do not know what the final outcome/decision was.

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

Actually, for wx trunk docs are in Doxygen. Doxygen has a command to spit out XML versions of the docs, and I've already got a script to parse that into Python objects (took about 30 mins, after all, this is Python ;-). From there, we can probably auto-generate both the docs and even possibly the SWIG bindings themselves, hopefully enabling Robin to finally consider the time between 12PM and 6AM as his free time. :slight_smile:

To deal with the C++ in the docs, what I think we'd need to do is just have a process where we store wxPython-specific docs in a file for that class (e.g. wxbutton_docs.i) and, when found during post-processing, any docs in it are used in place of the C++ docs.

This way everything's documented, and when some docs don't fit, we just fix them on a case-by-case basis.

Thanks,

Kevin

···

On Mar 11, 2009, at 3:23 AM, Werner F. Bruhin wrote:

Werner

_______________________________________________
wxpython-users mailing list
wxpython-users@lists.wxwidgets.org
http://lists.wxwidgets.org/mailman/listinfo/wxpython-users

33

Chris,
I feel that if you could just put your 100 little demos on a few Wiki pages it would be a great resource.
Because when one searches for a function your usage would be on the list, I find that the little
demos that I find are often the best learning tool.

Even if you add little or not text to the 100 little demos it would be great, I know that from the help you.
Phil

···

At 11:03 AM 3/11/2009, Christopher Barker wrote:

Werner F. Bruhin wrote:

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

That would be great -- also maybe links to the Wiki, though Wiki's are a bit ephemeral for that. I suppose we could have a Wiki page for each wx class -- then folks could add to them as we go. But maybe that level of docs really belongs in the main docs anyway, and we can save the Wiki for larger topics/examples.

I have close to 100 little demos that I've developed over the years to test various controls and methods. I'd like to put them somewhere, but haven't found any easy place to put them that would be organized enough to be useful, and easy for me to do. Anyone have any ideas?

-Chris

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

34

The demos provide code examples--have you looked at them?

Also, *WxPython in Action* is a very nice tutorial.

Randolph

···

On Mar 10, 2009, at 6:26 PM, David Lyon wrote:

With an expert eye... you probably can find everything...

For developers coming from other environments that are more
cleanly laid out.... it comes across as being very disjointed
and messy.

Code examples are my biggest issue on the class reference..

There appear to be none...

In Delphi and VB and every other language you got a code example of how to
use a method/function... you didn't need to go off to a search engine and
look for 10 minutes each time to see how to actually do something.

This is the biggest frustration for any new user....

Anyway...

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation

Thats it really...

and all will be good/better

On Tue, 10 Mar 2009 21:12:34 -0400, C M <cmpython@gmail.com> wrote:

Another version--for wxPython specifically and looking pretty nice it
seems to me,
is Andrea Gavana's:

http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html

And as Werner said, Boa Constructor has the wxPython API bundled up in
its help books, too.

Maybe I'm missing what you are looking for?

1) on the wxpython web site....

http://www.wxpython.org/onlinedocs.php
The link at the left says "Online wxDocs". Maybe your suggestion would
be to rename this "wxPython Class Reference" or API?

Now, you might take issue that this version is written in the C++ style.
Brings to the next point...

or

2) listed as "wxPython Class Reference"....

If you type those words into Google ("wxPython class reference"), that
brings you to:
wxPython API Documentation — wxPython Phoenix 4.2.2 documentation

Which is admittedly not well-titled at the top of that page at all and
arguably
not the prettiest documents ever.

or

3) on the F1 key in Boa Constructor (Help key)

The F1 key in Boa does bring up the wxPython class reference, but also

the

Boa help, Python help, and a few others. From there, though, it is a
matter
of one click on the words "wxPython API documentation" to bring you to

the

API.

Something simple like that..

As in... where people can actually find it....

Also, one can also just write, e.g., help(wx.TextCtrl) in an
interpreter for a quick
listing of methods.

Best,
Che
_______________________________________________
wxpython-users mailing list
wxpython-users@lists.wxwidgets.org
http://lists.wxwidgets.org/mailman/listinfo/wxpython-users

_______________________________________________
wxpython-users mailing list
wxpython-users@lists.wxwidgets.org
http://lists.wxwidgets.org/mailman/listinfo/wxpython-users

35

Kevin Ollivier wrote:

Hi Werner,

David,

David Lyon wrote:

...

I am not complaining - just providing feedback.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation
3) Get all the main classes (~50), properly documented
4) Get code examples for #3
5) Revise and update existing documentation

There was some discussion going on using Sphinx (see Andrea's version: http://xoomer.virgilio.it/infinity77/wxPython/) to generate the documentation - but I do not know what the final outcome/decision was.

The little I know about Sphinx is that it should allow for having code examples in the doc - maybe this could even be linked in/to the wxPython demo as the source for the code examples?

Actually, for wx trunk docs are in Doxygen. Doxygen has a command to spit out XML versions of the docs, and I've already got a script to parse that into Python objects (took about 30 mins, after all, this is Python ;-). From there, we can probably auto-generate both the docs and even possibly the SWIG bindings themselves, hopefully enabling Robin to finally consider the time between 12PM and 6AM as his free time. :slight_smile:

To deal with the C++ in the docs, what I think we'd need to do is just have a process where we store wxPython-specific docs in a file for that class (e.g. wxbutton_docs.i) and, when found during post-processing, any docs in it are used in place of the C++ docs.

This way everything's documented, and when some docs don't fit, we just fix them on a case-by-case basis.

Yep, that is the plan I am currently thinking/working towards, and will probably start putting some effort into it after 2.9.0. Some things still to be decided are:

* whether to generate the docs directly, let doxygen do it, or generate docstrings and let something like Sphinx do the rest.

* whether to generate the SWIG input files or just SWIG the interface files directly.

* Or maybe just dump SWIG and generate input for something else like SIP or maybe even do something crazy like flatten the C++ classes down to C functions and then create the extension modules and Python classes using something like Cython (formerly pyrex).

The most important thing about this transition is switching to use the interface files (the Doxygen input files) to auto-generate as much of wxPython and its docs as possible, that way much of the tedious and mind numbing work that I have been doing will simply vanish and the rest of it will be shared with the C++ team as they maintain the interface files. The nitty-gritty details of what to generate is still up in the air, but I'm looking forward to figuring it out and implementing it.

···

On Mar 11, 2009, at 3:23 AM, Werner F. Bruhin wrote:

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!

36

Robin Dunn wrote:

that is the plan I am currently thinking/working towards, and will probably start putting some effort into it after 2.9.0. Some things still to be decided are:

* whether to generate the docs directly, let doxygen do it, or generate docstrings and let something like Sphinx do the rest.

I vote for Sphinx -- it produces very nice results -- also I like having good docstrings anyway, for other tools to use.

* Or maybe just dump SWIG and generate input for something else like SIP or maybe even do something crazy like flatten the C++ classes down to C functions and then create the extension modules and Python classes using something like Cython (formerly pyrex).

wow! now there is a change! For what it's worth, the Cython guys are working on expanding support for C++, so maybe we won't need to flatten the classes first.

I don't know any details, but it was discussed at the recent Northwest Python Day in Seattle.

The most important thing about this transition is switching to use the interface files (the Doxygen input files) to auto-generate as much of wxPython and its docs as possible, that way much of the tedious and mind numbing work that I have been doing will simply vanish and the rest of it will be shared with the C++ team as they maintain the interface files.

very cool!

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

37

Hi,

Yes, there are, they just aren't embedded in the doc. The example are
in the separate demo application, an incredible resource that I have
never found in other open source projects.

Yes I grant it is good.

Put another way round.... it would be good to have some documentation
that is liked to the examples. So there is a direct and sequential
correlation.

Delphi and VB are products that cost a thousand dollars or more..

So what.... python is better...

If you want the
documentation to be better, then by all means please MAKE it better and
submit your results. That's how open source products improve.

That's an idea..

One of the difficulties with documentation for a product like this is
that everyone learns differently. For me, I learn best by example.

Right... me too.....

That's why I am asking for examples in the documentation.

1) Fix the links on the wxPython main documentation
2) Get all the C++ out of the wxPython documentation

I'm not sure that's a productive use of time.

So where is the documentation time being allocated ?

wxPython is a relatively
thin mapping of the C++ wxWidgets library. The core feature development
happens in the much larger wxWidgets team, and they're the ones who
document that core development, in C++ terms.

Fair point...

but... a python programmer doing applications doesn't want to think C++

Doing on the fly C++ -> Python translations just slows everything down...
surely?

It's not necessarily
productive to rewrite all of the arcana in that documentation. I agree
that the documents should describe where wxPython differs, and for the
most part, it already does so.

It's less productive for people to have innaccurate documentation when
they are trying to code some app.

Have you ever done any technical writing?

Yes. As I recall....

It is
very difficult to overestimate the incredible amount of time and effort
this requires, and for now most of would rather that the people who CAN
invest that time effort remain focused on programming.

You mean underestimate....

Then you are saying most people want to program and not write
documentation...

so what's new under the sun?

I'm getting too old to program... I want to write more documentation...

All I'm doing is giving feedback on the documention...

Thats all

David

···

On Wed, 11 Mar 2009 09:55:00 -0700, Tim Roberts <timr@probo.com> wrote:

38

David Lyon wrote:

Let's fix this...

Well, I'd like to use the term "improve" rather than "fix",

Ok - Lets improve it....

but yes,
your points are well taken. However, one of the big issues is that docs
take a lot of work, and it's not fun for coders, and it doesn't help
anyone that is writing the code actually solve a problem.

It's just a different skill. Your programmers shouldn't be writing the
documentation...

Also, docs that are not up to date are worse than hard to navigate docs,
so it would be really, really good if the core docs were essentially
auto-generated from the source.

That's just a procedural thing...

That's what the "new" wxPython docs are.
That was an effort Robin put in a couple years ago that has stalled --
picking up on it to get the results cleaner and neater and more easily
searchable would be great.

Let me know if could be assigned any task..

David

···

On Tue, 10 Mar 2009 22:29:19 -0700, Christopher Barker <Chris.Barker@noaa.gov> wrote:

39

David Lyon wrote:

Delphi and VB are products that cost a thousand dollars or more..
    
So what.... python is better...
  
Yes, but that's not the point. The point is that, because they charge
thousands of dollars for their products, Borland and Microsoft can
afford to have teams of technical writers on staff, separate from the
developers, who do nothing but write documentation. On a project like
wx, there ARE no technical writers. What we have are programmers
helping other programmers, for free. Those programmers are ALWAYS more
interested in the next fascinating tweak to the code, not in writing
documentation, and most developers really want it to remain that way.

Do you see what I'm saying? Commercial products have documentation
because the companies can afford to pay writers and programmers at the
same time, so development doesn't lag. An open source project doesn't
have that luxury.

By the way, I don't want you to think that I'm disagreeing with you in
any major way. I'm merely trying to point out why things are the way
they are, and why it is very natural for it to be this way in this kind
of a project.

I'm not sure that's a productive use of time.
    
So where is the documentation time being allocated ?
  
This little sentence makes so many assumptions! You assume that (a)
there is "documentation time" to be allocated, that (b) there is a
master project plan that has schedules for this kind of thing, and that
(c) there is some project manager who is doing the scheduling and
distributing assignments. Again, you WOULD have all that inside Borland
and Microsoft, but not in a project like wx. It is much more ad hoc.

It is
very difficult to overestimate the incredible amount of time and effort
this requires, and for now most of would rather that the people who CAN
invest that time effort remain focused on programming.
    
You mean underestimate....
  
No! It is VERY easy to underestimate the effort needed for good
technical documentation. Take your estimate, and multiply it by 3.

I'm getting too old to program... I want to write more documentation...
  
Believe me, there are a vast number of open source projects who would
dearly love to have someone like you on their team...

···

On Wed, 11 Mar 2009 09:55:00 -0700, Tim Roberts <timr@probo.com> wrote:

--
Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc.

40

David Lyon wrote:

That's just a procedural thing...

yes, but the procedures need to be in place before you can do much of the real work.

Let me know if could be assigned any task..

This was my point (3):

3) A BDFL for the docs -- someone that takes an interest and really follows through on making it happen -- not do all the writing, but the coordinating and motivating

we don't really have that person now -- Robin wants good docs, but is doing everything else. Andrea did some good work, but is also do many other things (like being kept awake by a crying baby :wink: )

So at this point, I don't think we have the procedures in place to make it easy for someone to contribute a little bit. It appears we agree that a new framework needs to be put in place, and have some good ideas about what that should look like.

If you want to take the bull by the horns and make it happen -- GREAT! Join the discussion, and work out with Robin and anyone else interested a plan for how to do it, and go for it!

Short of that some places for smaller scale contributions:
  - extra examples, etc, etc can be added to the Wiki.
  - The Wiki could use a good clean up an organizing
  - More examples and explanation can be added to the Demo.
  - more "wxPython notes" can be added to the main wx docs.

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov