[Doc-SIG] A plea

[Guido van Rossum]

> 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>

I didn't invent it -- I was appalled too when I first heard it, but it
surely conveys the intention very strongly. :-)

> > -- 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?)

Oh, forget it.  I meant using additional tools, but it's not important.

> 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.

Ah.  I agree.  I *thought* that some of the proposals I've seen were
written using a similar tool, but clearly not yours -- maybe I was
hallucinating.

--Guido van Rossum (home page: http://www.python.org/~guido/)