[Tutor] Documentation concerns. [example:__builtins__.zip, __builtins__.dict]

[Jorge Godoy]

Danny Yoo <dyoo@hkn.eecs.berkeley.edu> writes:

> Hmmm...
>
>
> I think we can attack this problem of missing examples: how about whenever
> we write a short example for a module function, that we add a small tag on
> the subject line of our emails, like [example:cgi] or
> [example:MySQLdb.connect]?

<snip />


> So if we find ourselves writing a small snippet of code that demonstrates
> the use of a function or class, perhaps tagging our subject lines with a
> short identifier like [example:foo] will help people out.
>
>
> Any thoughts on this?

I like the idea but there's a problem: changing APIs. 

There's also another problem: human beings. ;-)


If I write something and name it '[example:something]'. You find an
error and reply to it. Then we have two messages, where we could have
just one. Then, someone wants to point out a third way or ask for
information on your code. Then there's a third message, a fourth
message and so on. 


I find the Wiki idea used in lots of places --- including Python ---
ideal for such documents. People can submit pages and those can be
updated anytime.

We could put the python-tutor Wiki address on the footer of every
message as an aid to newbies such as myself :-) It would show them
where they have to look for information or better understanding of
things. 


But, as I said before, the module documentation is, at least to me,
the first place to search. I'm not looking at the source code (not all
the time, only when I can't find anything useful on the web) but I'm
using pydoc all the time. 

This is, IMHO, one big enhancement: a module that can be used
correctly with the output of 'pydoc module'. 


-- 
Godoy.    <godoy@metalab.unc.edu>