What is important (was Re: [Doc-SIG] [ANNOUNCE] SantisimaInquisicion)

[Peter Funk]

Hi!

David Ascher wrote:
[...]
> Generally, I think that the DOC-sig spends too much time arguing about
> specific markups and trendy technology (sorry, I'm getting really
> frustrated at the XML LPHBTSP (that's 'alphabet soup' without vowels), and
> not enough with the marketing aspect.  
> 
> *If the problem is to encourage average Python coders to markup their
> docs*, then you need to make it simple *and Python-like*.  Define a
> Pythonic syntax (e.g what Jim Fulton uses in the StructuredText.py
> module), provide a CGI script which has a "PUT" button which will take a
> marked-up .py file, creates a hyperlinked TOC for that module, snazzy HTML
> pages and whatnot, automatically add said module to some centralized
> repository of 'cool documented modules', and folks *will* learn the
> markup.  Especially if you provide a few modules which show examples of
> the markup and show how trivial it is.
> 
> On the other hand, if you put up a page which makes Python code look more
> like TeX or XML, why in the world do you expect people to bother?

I agree with David.  I've joined the list only recently (some
weeks ago).  As someone who has yet much to learn, I think that the
current documentation for Python and the module library is very good.
Unfortunately some very important parts are still missing: Something
like Fredrik Lundhs "An Introduction to Tkinter" ---also it is still
somewhat incomplete in some regions--- would be a _VERY_ useful addition
to the library documentation.  

Spending time on something like this seems far more important to me than
this discussion about the topics introduced in Chapter 8 (Future
Directions) of Documenting Python.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)