On 5 Dec 2005 10:53:36 -0800, [EMAIL PROTECTED] (Aahz) wrote:
>In article <[EMAIL PROTECTED]>,
>BartlebyScrivener <[EMAIL PROTECTED]> 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
--
http://mail.python.org/mailman/listinfo/python-list
