[Python-Dev] Best practice for documentation for std lib

[R. David Murray]

On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <guido at python.org> wrote:
> On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev at masklinn.net>wrote:
> 
> > The points here are that there's a single source of truth (so we can't
> > have conflicting docstring and rst documentation), and documentation
> > becoming outdated can be noticed from both docstring and published
> > documentation.

Another thing that hasn't been mentioned about docstrings vs rst docs,
is that even when the text is identical, it generally isn't.  By that I
mean the rst docs have ReST markup, but the docstrings don't.  So using
autodoc doesn't just mean adding autodoc to our doc building toolchain,
it *also* means adding support in pydoc for turning ReST into plain text.
And that still leaves the markup in the docstring, where it will be very
distracting while actually reading the source code.  Which, unlike other
commenters, I spend more time doing that than I do using help (and that
doesn't apply to just the stdlib for me).
 
> >
> Another case of DRY madness.
> 
> It seems too many programmers see documentation as unpleasant red tape they
> want to cut through as quickly as possible, instead of an opportunity to
> communicate with their *users*. To the contrary: users should be the most
> important people in the world if you're writing code that's worth
> documenting at all.

I won't pretend that I find having to edit two places when updating
fundamental documentation pleasant, but...

I find that as often as not I want to word things *differently* in
the docstring vs the rst docs for the same function.  Sometimes the
difference is subtle; most often it is an omission of detail along the
lines Guido suggests.  But when writing the rst version, it generally
isn't that I'm simply continuing on after the first paragraph; instead,
the organization of even that starting text is different, because
I'm aware that the reader has a different mindset (quick help vs
reference documentation) when reading the two texts.[*]

As with the question of NEWS items versus checkin messages, the intended
audience, or in this case the mindset of the intended audience, is
*different*, and so the text should very often be different as well[**].

--David

[*] I posit that this is even *more* true for those who say they only
use help and only fall back to the full docs when the docstrings
aren't enough.

[**] I also wonder if long function docstrings have a negative impact on
usability in IDEs that pop up windows with docstring information in them.