[Doc-SIG] PEP-0216

[Tony J Ibbs (Tibs)]

Moshe Zadka elucidate what he saw us needing to produce for 2.1:
> a. A way to have all Python documentation inside the modules, so
>    people will have good examples to follow.
> ...etc...

My only worry is a little vagueness round the edges of the description
whenever you refer to "a module's documentation". I remember Eddy saying,
yonks back:

> There are three kinds of `documentation' I want associated
> with a tool:
>
> comments -- which I read when I'm modifying the tool
> manuals  -- which I read before trying to write code which uses
>             the tool
> docstrings -- which I read when I find the tool in my hands

Whilst one might argue with the *detail* of those descriptions, I believe
that there is a very distinct diffference between manuals and docstrings (in
much the same way as there is between books and memos).[1]

I assume that when you say "documentation" you *don't*, in fact, mean
"manuals", but I have learnt to be cautious, because I *have* seen people
conflating the two in the past, and I want to make sure we know what we
aren't doing...

I think I'm particularly worried by the statement "A way to have all Python
documentation inside the modules"...

(of course, if you just mean that installing a new module (in the Catalog
sense) just ensures that its documentation (of all forms) also gets
installed, somewhere, then I am not worried - but that's a different issue)

I think I'm also upset if you expect people writing manuals to have to use
the same format designed for docstrings, since the AIMS are different -
docstrings must be pleasant to read "as is", by people inside the code, or
people using a class browser, but very few people (um, well) read HTML or
XML or TeX raw, and most people don't even *write* them "raw". And in "real"
documentation you often want to have closer control over what is going on
than StructuredText will allow.

[1] I cite the parlous state of much of the Microsoft technical
documentation, which has clearly been cobbled together from all of the notes
and memos and (indeed) documentation strings that could be found. This gives
a large body of text, with no real organisation, occasional contradiction,
and no *flow* - there is, in general, no way one can navigate through a
particular problem space without use of the index.

Tibs, feeling he should be worried *just in case*

(but not, noway, worried enough to stop us getting something done, honest
guv)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)