[Tutor] Documentation concerns.
roy ollis
roypython@hotmail.com
Fri May 23 02:42:01 2003
if the code keeps changing would heavily commenting the code with
explainations and examples work as a form of documentation. if you wanted
to see how something works just look at the source or .py files. perhaps
even create a module (or full program shell) that dosn't ignore comments but
displays them in a pop up with line by line explainations of what the code
is doing and have a "next line" (or operation) button to slow the processing
down so the running program can be examined one step at a time while
running. perhaps a three pane frame, one is the program running as intended,
one pane is the code, and the third pane is the comments, all three panes
syncronized so that you can see the code, explaination and result all at the
same time and mr gauld said there are many definitions of "advanced skill
level" for programmers. to me an advanced is someone that can look at a
program someone else has written and see the problems so quickly it amazes
tham everyone dosn't see it. (almost like bugs were typed in a flashing
neon florcent font). and thanks to many on this list. they're beyond
advanced, they can explain the problem so the novice can understand the
bugs too and what to do next time rather than just parroting code with no
idea why or how it works. (and i'm still a novice, still parroting more
than programming). thanks to all the great teachers on the list.
>From: Paul Tremblay <phthenry@earthlink.net>
>To: tutor@python.org
>Subject: Re: [Tutor] Documentation concerns.
>Date: Fri, 23 May 2003 01:18:11 -0400
>
> >
> > Magnus Lyckå <magnus@thinkware.se> writes:
> >
> > > Perhaps the Python documentation needs to contain even more
> > > suggestions to try out and experiment with features.
> >
> > IMHO it would benefit a lot of examples.
> >
> > E.g.: Perl's first page on the CGI module:
> >
> > ----------------------------------------------------------------------
> > CGI(3) User Contributed Perl Documentation
>CGI(3)
> >
> > NAME
> > CGI - Simple Common Gateway Interface Class
> >
> > SYNOPSIS
> > # CGI script that creates a fill-out form
> > # and echoes back its values.
> >
> > use CGI qw/:standard/;
> > print header,
> > start_html('A Simple Example'),
> > h1('A Simple Example'),
> > start_form,
> > "What's your name? ",textfield('name'),p,
> > "What's the combination?", p,
> > checkbox_group(-name=>'words',
> > -values=>['eenie','meenie','minie','moe'],
> > -defaults=>['eenie','minie']), p,
> > "What's your favorite color? ",
> > popup_menu(-name=>'color',
> >
>-values=>['red','green','blue','chartreuse']),p,
> > submit,
> > end_form,
> > hr;
> >
> > if (param()) {
> > print "Your name is",em(param('name')),p,
> > "The keywords are: ",em(join(",
>",param('words'))),p,
> > "Your favorite color is ",em(param('color')),
> > hr;
> > }
> >
> > ABSTRACT
> > This perl library uses perl5 objects to make it easy to create
>Web
> > ----------------------------------------------------------------------
> >
> > The SYNOPSIS gives you examples of how to use objects, how they
> > work. The documentation goes on and explain the more intricated uses
> > of such a module.
> >
> >
> > Python's CGI first page:
> >
> > ----------------------------------------------------------------------
> > Python Library Documentation: module cgi
> >
> > NAME
> > cgi - Support module for CGI (Common Gateway Interface) scripts.
> >
> > FILE
> > /usr/lib/python2.2/cgi.py
> >
> > DESCRIPTION
> > This module defines a number of utilities for use by CGI scripts
> > written in Python.
> >
> > CLASSES
> > FieldStorage
> > MiniFieldStorage
> > UserDict.UserDict
> > FormContentDict
> > FormContent
> > SvFormContentDict
> > InterpFormContentDict
> >
> > class FieldStorage
> > | Store a sequence of fields, reading multipart/form-data.
> > |
> > | This class provides naming, typing, files stored on disk, and
> > | more. At the top level, it is accessible like a dictionary,
>whose
> > | keys are the field names. (Note: None can occur as a field
>name.)
> > | The items are either a Python list (if there's multiple values)
>or
> > | another FieldStorage or MiniFieldStorage object. If it's a
>single
> > | object, it has the following attributes:
> > |
> > | name: the field name, if specified; otherwise None
> > |
> > | filename: the filename, if specified; otherwise None; this is
>the
> > | client side filename, *not* the file name on which it is
> > ----------------------------------------------------------------------
> >
> > There's no indication on, how to import the module ("import cgi"?
> > "from cgi import *"?), on how to start a simple cgi with it, etc.
>
>Amen! Amen!
>
>I missed some of the beginning of this thread, but I believe very
>strongly that good documentation would help the open source community
>almost more than anything. Good documentation incudes *concrete*
>examples, not abstractions which by themselves are confusing.
>
>Contributing documentation is perhaps a way we non-programmers (at
>least non-skilled programmers) can really help out.
>
>I know keeping up with documentation is difficult, given that code is
>always changing, and that coders usually hate to write documentation.
>But it is very discouraging to spend hours, or days, or even weeks
>struggling with a problem for simple lack of a good explanation.
>
>Poor documentation has been the major frustation for me in switching
>from Mac to Linux.
>
>Paul
>
> >
> >
> > I try putting usage examples on my docs. They help me reminding how to
> > use something --- it doesn't matter how good is the description,
> > sometimes you just want to see one example using the function --- and
> > will certainly help other people too.
> >
> >
> >
> > See you,
> > --
> > Godoy. <godoy@metalab.unc.edu>
> >
> > _______________________________________________
> > Tutor maillist - Tutor@python.org
> > http://mail.python.org/mailman/listinfo/tutor
>
>--
>************************
>*Paul Tremblay *
>*phthenry@earthlink.net*
>************************
>
>_______________________________________________
>Tutor maillist - Tutor@python.org
>http://mail.python.org/mailman/listinfo/tutor
_________________________________________________________________
Add photos to your e-mail with MSN 8. Get 2 months FREE*.
http://join.msn.com/?page=features/featuredemail