Okay, I guess it's time for me to step up to bat. I write technical
documentation for a living, so I'm qualified for that end of it. I also
know (knew?) enough about wxPython to write a few basic programs, so I'm
probably at that point where I know enough to know enough.
But before I do any work, I need to do some thinking about what questions I
need to ask to find out what you all do, how you use documentation and
etcetera. That will help me define what form and structure the docs should
have. Which, in turn, will save a lot of rewriting.
I'll also need people who technically review the documents, to ensure that
what is said is indeed true and correct.
Let me think about it; I'll start drawing up some questions and such.
As many have mentioned here, the problem with documentation is that those
qualified to do it won't need it. The way to get around this is to make the
process as easy as possible, so that any useful piece of information can
find its place with minimum effort.
Enclosed is a little package to get the documentation started. It contains
a skeleton directory structure and a simple tool that generates annoted and
hyperlinked directory listings. Just put a file in the right place and make
an annotated reference, and it becomes part of the documentation.
Several people have already volunteered to maintain and contribute to the
documentation. So we only need an archive host to get the ball rolling. We
can even start to collect the formal documentations, tips, code snippets,
faqs and what-have-you right now.
Propaganda pitch for this approach:
o It is simple. You can start using it in a few minutes.
o It allows any files and links to any urls. No prior agreement on file
format is necessary.
o The metadata is in flat ascii formats. They are well structured and
easily parsable. It will be easy to migrate to more powerful tools when
this thing outlives its usefulness.
o There is little risk of drying up, because anyone interested can pick it
up and continue.
o It is easy to further automate the process when the need grows. Following
is an example of the kind of information that is needed for each piece of
what: program to run demo modules