[wxPython] Re: wxPython Documentation

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

[wxPython] Re: wxPython Documentation

David Priest
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.


_______________________________________________
wxPython-users maillist  -  [hidden email]
http://starship.python.net/mailman/listinfo/wxpython-users



Reply | Threaded
Open this post in threaded view
|

Re: [wxPython] Re: wxPython Documentation

Huaiyu Zhu-4
                Some tools to kick start the documentation

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
  documentation:

what: program to run demo modules
place: /examples/tools/run.py
cite: /examples
cite: /examples/demo
cite: /faq/how-to-use-demo

--
Huaiyu Zhu [hidden email]


qdindex.tgz (10K) Download Attachment