Re: Bitching about the documentation...

On 5 Dec 2005 10:53:36 -0800, aahz@xxxxxxxxxxxxxxx (Aahz) wrote:

>In article <1133806205.373629.178540@xxxxxxxxxxxxxxxxxxxxxxxxxxxx>,
>BartlebyScrivener <rpdooling@xxxxxxxxx> 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
.

Relevant Pages

  • Re: DataGridView column order?
    ... I thought that was reasonably clear in my original post, but if not I apologize. ... Regardless, there is no order defined for any of these case. ... documentation makes no mention about how the property descriptors are to be ... I recognize why the documentation doesn't define this. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: [PATCH] Re: THE LINUX/I386 BOOT PROTOCOL - Breaking the 256 limit
    ... I got enough attention... ... I just wait for documentation update... ... Regardless... ... send the line "unsubscribe linux-kernel" in ...
    (Linux-Kernel)
  • Re: [PHP] foreach() using current() strange beahvior
    ... clarify these subtleties. ... Regardless of additional documentation or not, ... scalable system for accessing system services | ...
    (php.general)
  • [PATCH, RFC 0/3] Improvements to the tracing documentation
    ... At the kernel panel at the Linux Foundation Collaboration Summit, ... mentioned that the documentation for the tracing subsystem could be ... I'm not sure the documentation is 100% correct, but by submitting it, ...
    (Linux-Kernel)
  • Re: I am ANGRY with Debian.
    ... analogies fall short because documentation is not software, regardless of Debian's dogmatic claims to the contrary. ... If you mean with documentation some files you have on your computer, then they are of course software. ...
    (Debian-User)