[Doc-SIG] A plea

Tony J Ibbs (Tibs) tony@lsl.co.uk
Fri, 30 Mar 2001 16:26:47 +0100


Guido van Rossum wrote:
> Fine.  But please do eat your own dogfood

Yuck. That's a horrible image - have you ever *tasted* dogfood? Or
*smelt* it? <shudder>

> -- write all your docs, your
> spec and your API docs and a tutorial, using your own language,
> without cheating.  Then show us the source for all that documentation.

Hmm. Two answers - one yes, and one no.

Categorically yes, as I try to write decent docstrings, and thus have to
talk about what the software does. And the docstrings have to be in the
format (of course they do, 'twouldn't be much good else).

(by the way, I'm not sure what you mean by "cheating" - how could one
cheat? It either goes through the tool and comes out the other end as
one wishes, or it doesn't, surely?)

But also categoricallly no - *I* am not one of the people who believe
that all documentation should be written in this format - it's for
docstrings, and if it's also useful for not-using-TeX (name your
favourite markup language or tool not to use) then that's a coincidence.
And not one I necessarily want to push.

There is *no* way that I can expect to write text that actually looks
like the fat.html file, for instance, in a docstring tool (you might say
I shouldn't want to write stuff that looks like that in anything, and I
might agree, but let's pretend we don't say that).

I *like* decent tutorials, reference manuals, etc (I *very* highly
respect people who are good at writing them). I've been arguing
*against* Ka-Ping Yee (excellent person though he be) on his wish to use
docstrings for everything. I shan't change now.

But *please* remember that I'm serious about having only a little time
to spare. I took on this task (reluctantly) in the first place because I
saw the Doc-SIG going for yet another round of excitement followed by
abrupt disappointment. I *knew* I could get something done fairly
quickly. The "fairly quickly" got scuppered by a death in the family,
but the principle stands. Then Edward Loper joined in, and we were doing
quite well on getting towards a PEP or two.

Because of only having a little time, I need to decide how to *invest*
that time. Some things I *know* will take a long time to resolve well.
They make sense to leave alone for a while. Also, some answers come out
"in the wash" once one has experience. Those are best left for a while
as well. Deciding what belongs in what category is part of being a
worker on the Doc-SIG. And I still assert that relevent experience from
elsewhere should also be taken on board in making such decisions.

I know we have philosophical differences about all of this. I *feel*
that *my* best way of explaining things is with an example
implementation and the documentation that goes with it. Something solid
to discuss makes life a lot easier (I cite the types-sig as another
example - now *that*s exciting stuff).

[[[Of course, not feeling that someone is going to decide on a
Pod-variant whilst I'm away would help (I wish I could remember why Pod
was discarded as a possibility in the past, but I *really* don't have
time to look now).

Why couldn't all of these enthusiastic people have been around at the
end of last year, eh?]]]

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)