Please get your email addresses correct. I keep getting them. Thanks.
----- Original Message -----
From: Michael Foord
To: Ralf Gommers
Cc: doc-sig@python.org
Sent: Wednesday, April 14, 2010 11:22 AM
Subject: Re: [Doc-SIG] epydoc reST markup for stdlib docstrings
On 14/04/2010 17:13, Ralf Gommers wrote:
On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzy...@voidspace.org.uk>
wrote:
On 14/04/2010 16:48, Ralf Gommers wrote:
The vertical whitespace vs tags is a taste issue, I agree, from a
developer perspective. From a user perspective however, the numpy standard is
clearly more readable in a terminal. That's why it looks the way it does. And
reading docstrings in a terminal is not a fringe use case by the way.
I would say that reading docstrings in a terminal is the *main* use case
- but that is why I tend to value the vertical space highly and personally
prefer the less verbose way.
You're a core developer (I think). But for the *average* user, do you
really think tags are fine? Earlier in this thread there was a mention of
people that love to read XML. I'm exaggerating a bit of course, but this is
similar. Whitespace beats tags for readability.
Well, docstrings that take up several screens worth of console and scroll out
of view like merry abandon are horrible. We should do real usability testing
(with 'real' users) if we really want an answer.
Michael
Ralf
--
http://www.ironpythoninaction.com/
------------------------------------------------------------------------------
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
