[Doc-SIG] RE: New PEP: reStructuredText Standard Docstring Format

[Moore, Paul]

(Third try at this - I'm groping for a way to express my point here...)

I only really have one issue with the document, which is that it reads a
little too much like it's trying to be the "how to write your comments"
section of a programming standard.

Wait - before you start throwing rocks at me, let me explain...

As I was reading it, I had no complaint with any of the details, but there
was this nagging feeling in the back of my mind saying "Why should I agree
to these rules? Even Guido doesn't have the right to tell *me* how to write
my documentation!" There isn't enough emphasis on why using reST in my
docstrings provides *me* with benefit. At the end of the day, we're all
pretty selfish about how we write our code - we document the bits we think
we, personally, might not understand later, and we excuse the areas where we
skip documentation with the excuse that "it's obvious". (OK, maybe it's just
me - but I suspect most people have a little bit of this attitude)

I'd suggest that you add a "Benefits" section, explaining the advantages to
the individual programmer - *not* to the community as a whole - of the
proposal. My characterisation of the benefits would be:

  - The proposed format (reST) is entirely readable in
    plaintext format, and many of the markup forms match
    common usage (e.g., ``*emphasis*``), so there is no
    significant downside to using it (beyond the initial
    learning curve) [1]_
  - Tools will become available in the (hopefully near)
    future, which will allow me to generate HTML for
    online help, and PDF/DocBook/LaTeX (?) for printed
    documentation, essentially "for free" from the existing
    docstrings. [2]_
  - Other automated tools will understand my documentation
    strings, and be able to respect my formatting requirements
    [3]_

.. [1] Actually, it's arguable that the similarity to "existing
       practice" makes getting the syntax right *harder*. I never
       get footnote syntax right without checking (and I may have
       got this lot wrong!) This may be because of all the recent
       changes, but it is still something that probably needs
       covering in a Q&A. "Q: Won't the superficial similarity to
       existing markup conventions cause problems, and result in
       people writing invalid markup (and not noticing, because
       the plaintext looks natural)?"
.. [2] It's pretty important *not* to give the impression that
       these tools could be "vapourware". People are cynical...
.. [3] This one's vague - I'm sort of thinking about pydoc.

Interestingly (and possibly relevantly) it's not clear to me that these
benefits are overwhelming. It's more a case of the cost being minimal [4]_,
and the potential benefits being reasonable. Maybe we need to focus more
strongly on getting tools working. Something on the level of "look - I
generated a help file and some printed documentation, and pydoc produces
well-formatted information - all without doing anything more than using reST
in my docstrings". People respond better to demonstrations than to
standards...

.. [4] Which argues that people may well end up only using subsets
       of the full reST spec - just the bits they remember or find
       particularly hard to express any other way [5]_ ...
.. [5] So we need to consider how the dps will cope with the sort-of
       reST which may be written by (for example) someone who didn't
       know that reST had a table construct, and just typed in a
       table in a "natural" ASCII-art form. In other words, how
       forgiving is reST going to be of "not quite right" constructs?

I know the tools are coming (and I'm not doing much to help, so I shouldn't
criticise). But I'm a little concerned that a standard without supporting
"gee whizz" tools could turn some people off the idea, rather than
generating enthusiasm...

Paul.

PS I just noticed that I manually numbered the footnotes in this message -
even though I needed to renumber at one point. In practice, I don't think
I'd ever use the ``[#]`` notation for auto-numbering. It's too hard to
follow in "raw text" form. Just a data point...