Bitching about the documentation...

[A.M. Kuchling]

On Tue, 6 Dec 2005 00:05:38 -0500, 
	François Pinard <pinard at iro.umontreal.ca> wrote:
> It's a relatively recent phenomenon that maintainers go berzerk, foaming 
> at the mouth over forms, borders, colors, and various other mania!  :-)

It's largely to ensure that the ideas aren't lost.  E-mail sits around
in an inbox until it gets deliberately deleted or gets lost in a disk
crash or system upgrade gone wrong.  Usenet posts fall out of the news
spool and get buried in Google's archives.

For example, here are the oldest messages in my mailbox:

   1     Mar 24 Whitesell, Ken  (3.5K) [PyCON-Organizers] Feedback from a first-
   2     Mar 28 Martin Maney    (1.4K) Improving "The Python DB-API interface"
   3   T Mar 28 MW Mike Weiner  (1.0K) RE: [Pycon2005-attendees] Found items
   4   + Mar 28 Mark Wittner    (0.8K)  *¬>
   5   + Mar 29 Anna Ravenscrof (0.9K)   >
   6  s+ Mar 28 David Goodger   (1.4K) Re: Q. about Emacs on MacOS
   7   + Apr 04 Neal Norwitz    (250K) Re: PyCon treasury question
   8     Apr 28 Thorsten Leemhu (0.7K) python-crypto RIPEMD160 and SHA256 not 64
   9   + May 01 nemir nemiria   (0.4K) regular expression how-to suggestion.
  10     May 07 Brian Hook      (0.3K) pycrypto
  11     May 23 John Lambert (W (3.7K) python howto: regular expressions - issue
  12   T Jun 01 Tim Parkin      (2.5K) pydotorg redesign
  13   T Jun 02 Neal Norwitz    (2.3K) Re: [Python-Dev] Vestigial code in thread
  14   + Jun 09 Jacob Rus       (0.5K) python regular expression howto
  15     Jun 17 Zed Lopez       (0.5K) [pct] decrypting a ciphertext with an RSA
  16     Jun 21 Skip Montanaro  (1.3K) Re: [Pydotorg] Python Homepage: possible
  17     Jun 27 Osvaldo Santana (0.7K) [marketing-python] Python Powered in Core
  18   + Jul 09 Martin Kirst    (0.3K) pycrypto pre build binaries for windows,
  19     Jul 10 Jeff Rush       (0.9K) [PyCON-Organizers] Two Good Developments
  20     Jul 13 mso at oz.net      (2.5K) Re: [Quixote-users] Quixote 2 Docs
  21   T Jul 15 Nick Jacobson   (0.4K) py3k

#2 from Martin Maney is a suggestion about a web page I have on the DB-API.  
#8 is a pycrypto bug report; I think the bug is fixed now, but would have 
to check.
#9 and #11 are suggestions for the regex HOWTO.
#10, #15, #18 could be suggestions, bug reports, or questions; hope
they're not questions or bugs, because the chance of them being
answered is zero at this point.

You may suggest that I should process my e-mail more promptly.  True,
but that's very hard; there's always newer e-mail coming in.  Do less?
I'd love to, but that doesn't seem to be a viable option.

I could just delete all this mail, but I still have the hope of
someday doing a rewrite pass on, say, the regex howto, going through
all the suggestions and making some changes accordingly.  I am,
however, drifting toward the Linus Torvalds approach of mail handling:
delete messages after six months.  If the message was important,
they'll resend it.  A pity that it means Martin's suggestions, and
Thorsten's bug, and Nemir's suggestion, get discarded.

This is why things need to go into public trackers, or wiki pages.
There, at least their content is available to someone else; if
someday, someone else does a new regex howto, they could use the
suggestions and patches that have accumulated over time.  

--amk