[Doc-SIG] A plea
Guido van Rossum
Fri, 30 Mar 2001 12:44:58 -0500
> 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
--Guido van Rossum (home page: http://www.python.org/~guido/)