Bitching about the documentation...

[Bengt Richter]

On 5 Dec 2005 10:53:36 -0800, aahz at pythoncraft.com (Aahz) wrote:

>In article <1133806205.373629.178540 at g44g2000cwa.googlegroups.com>,
>BartlebyScrivener <rpdooling at gmail.com> wrote:
>>
>>Yes, well, regardless of your beef with the person who complained about
>>documentation, I respectfully submit that it is not so easy to help out
>>with documentation. I'm a professional writer and author with a keen
>>interest in open source, but the moment you look to contribute or try
>>to help with the documentation you are asked to learn LaTex or DocBook,
>>which, I'm sorry, I am not going to do.
>
>This is not true.  You are welcome to submit plain text patches; reST
>patches are even better.  There has been a lot of confusion on this point
>in the past (to which I responded by submitting a bug report and getting
>the docs about submitting patches changed).  Can you point out where
>you're getting this impression from so we can make further improvements
>to the process?  Or do I (and others) simply need to keep repeating this
>point endlessly?
With all due respect, ISTM submission of comments and additions to docs.python.org
web pages could be made easier. There is a link at the bottom of many/most doc pages (all?) to

    http://docs.python.org/lib/about.html

ISTM it would be easy to have an addditional clickable submit-comment link to e.g. a generated
framed page with the referrer doc page on top and a comment text box at the bottom (or whatever
looks good, with scrolling  for view of orig doc page), to make it easy to comment. A few check boxes
could categorize as to spelling/typo corrections vs adding helpful links or cross references,
vs wiki references, vs just griping, vs adding whole sections, etc.

A little more effort could present the referrer page with clickable paragraphs and other elements,
to zoom in to what the commenter wants to comment on. And an automatic diff could be prepared for editors,
and the submitted info could go in a structured file for automated secure web access by editors to ease review
and presumably sometimes pretty automatic docs update. Adherence to submission guidelines could be
enforced somewhat by form checks etc.

For general volunteering, a page could be generated automatically showing counts of failed search
subjects. Search could be modified with a form to log a gripe/suggestion about a failed search, that would
also be accessible. The failed search-term count display could also show a count of associated
comments.

We could agree on newspost tag-lines to enable automatic harvesting of gripes, topic suggestions, links,
etc from c.l.p newslist archives. E.g.,

[BeginPythonDocsHarvest]
    (automatically harvestable info to go here, format TBD, but maybe
     rfc2822 could be looked for, or XML or rest etc?)
[EndPythonDocsHarvest]


E.g, to add a link to this (the one you are reading) post/thread to a database
of ref links for various doc pages that would ultimately show up as a single
clickable [refs] item at the bottom of pages that have refs, one could
tag a post with something like

[BeginPythonDocsHarvest]
LinkToThisThread: http://docs.python.org/about.html
[EndPythonDocsHarvest]

I guess I better stop ;-)

Regards,
Bengt Richter