Re: metadocumentation (keyword help)

From: Jacek Generowicz (jacek.generowicz_at_cern.ch)
Date: 01/07/04 

Date: 07 Jan 2004 13:44:57 +0100

I always wonder whether I should post concise articles, or wordy ones,
covering all possbile assumpitons and misconceptions.

It appears that, usually, I get the balance hopelessly wrong :-( Or,
maybe, that's just what life is like in a large public forum; whatever
you say, there will always be hundreds of people who misunderstand you.

Thomas Heller <theller@python.net> writes:

> Jacek Generowicz <jacek.generowicz@cern.ch> writes:
>
> > Yes, but this actually does not work out of the box (on any of the
> > GNU/Linux, Mac OS X, and even Windoze installaitions I have tried). You
> > get an error message complaining about the absence of HTML
> > documentation and setting PYTHONDOCS. So, to rephrase my question ...
> >
> > Where can I find clear instructions on how to install and configure
> > the Python documentation which is necessary to make the following
> > work:
> >
> > >>> help('and')
> >
> > ?
>
> Download the HTML archive from
> <http://www.python.org/doc/current/download.html>, and unpack this in a
> temporary directory. Leave the directory structure intact - in Winzip,
> make sure the 'Use Folder Names' checkbox is checked.
>
> This creates a Python-Docs-2.3.3 subdirectory. Copy everything in this
> directory (including subdirectories) into your c:\python23\Doc folder
> (normally there is a single Python23.chm file in it), and you're done.

Does someone who writes

> > GNU/Linux, Mac OS X, and even Windoze
                             ^^^^ ^^^^
really look like someone who is looking for instructions on fixing his
Python installation on a M$ operating system ?

Jacek Generowicz <jacek.generowicz@cern.ch> originally wrote:

> Where can I find concise, clear documentation[*] describing what one has
> to do in order to enable Python's internal help to be able to provide
> descriptions of Python keywords ?
>
> I am in a situation where I have to give Python novices the ability to
> fix this for themselves easily.
>
>
> [*] Failing "concise" and "clear", how about "complete and correct" ?

I teach an introductionary course on Python. One of the key messages
that I try to convey is that with Python's excellent introspection
capabilities, the built-in help, and the Python web site, you have
pretty much all the information you need at your fingertips. In the
course, I politely refuse to answer any questions which the student
can easily answer himself by using the interactive help. The point is
that I hope that the studens will go away with the ability to find
most things out for themselves. In this context, I would like them to
be able to find out for themselves how to fix the keyword
documentation, which is why I phrased my original question thus:

> Where can I find concise, clear documentation[*] describing what one
> has to do in order to enable Python's internal help to be able to
> provide descriptions of Python keywords ?

Note, I did NOT say "How do I ...", I said "Where do I find
[...] documentation ...".

I am NOT interested in a recipe posted here. I want to know where to
find the official instructions on how it is done, so that I can show
newbies how to find the information themselves.

"Give a man a fish, and he can eat for a day. Teach a man to fish ...",
and all that.

If these instructions are, as it seems, absent, then I would
appreciate advice on what I can do to make them appear in the
appropriate place, and what the appropriate place might be.

I recognize my impatience with poor documentation as a pathological
flaw in my characer, which is why I am asking for help in
finding/creating this documentation here.

Relevant Pages

  • Re: Finding installed package files
    ... for making installation information more easily accessible? ... >> somewhere where more information about the key parts of the package ... >> As an example I installed the latest Python on Fedora 3. ... what one would expect is a form of help documentation much more integrated ...
    (alt.os.linux.redhat)
  • Re: Bitching about the documentation...
    ... > a language need complaints about the language? ... To give potential adopters of Python a more even handed view ... but sometimes "constructive criticism" means ... I have found Python's documentation to generally be excellent. ...
    (comp.lang.python)
  • Re: My Python annoyances
    ... incomplete documentation, a maze of little platform-specific quirks to ... Python base classes have changed behavior. ... perhaps the best introduction to the language when it was written. ... I filed a bug report. ...
    (comp.lang.python)
  • Re: My Python annoyances
    ... incomplete documentation, a maze of little platform-specific quirks to ... Python base classes have changed behavior. ... perhaps the best introduction to the language when it was written. ... I filed a bug report. ...
    (comp.lang.python)
  • python-dev Summary for 2005-12-16 through 2005-12-31
    ... Python-dev is in love with Python, though sometimes too much, Fredrik ... Contributing thread: ... Want to help out with the Python documentation? ...
    (comp.lang.python)