[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation

[Steven D'Aprano]

Nick Coghlan wrote:
> On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl at gmx.net> wrote:
>> Hi,
>>
>> at <http://dpo.gbrandl.de/contents>, you can look at a version of the 3.2
>> docs that has the upcoming commenting feature.  JavaScript is mandatory.
> 
> Very nice!
> 
> I'm not sure what to do about the discoverability of the comment
> bubbles as the end of each paragraph. I initially thought commenting
> wasn't available on What's New or the Using Python docs until seeing
> where the blue comment bubbles appeared in the math module docs.

I wonder what the point of the comment bubbles is? This isn't a 
graphical UI where (contrary to popular opinion) a picture is *not* 
worth a thousand words, but may require a help-bubble to explain. This 
is text. If you want to make a comment on some text, the usual practice 
is to add more text :)

I wasn't able to find a comment bubble that contained anything, so I 
don't know what sort of information you expect them to contain -- every 
one I tried said "0 comments". But it seems to me that comments are 
superfluous, if not actively harmful:

(1) Anything important enough to tell the reader should be included in 
the text, where it can be easily seen, read and printed.

(2) Discovery is lousy -- not only do you need to be running Javascript, 
which many people do not for performance, privacy and convenience[*], 
but you have to carefully mouse-over the paragraph just to see the blue 
bubble, and THEN you have to *precisely* mouse-over the bubble itself.

(3) This will be a horrible and possibly even literally painful 
experience for anyone with a physical disability that makes precise 
positioning of the mouse difficult.

(4) Accessibility for the blind and those using screen readers will 
probably be non-existent.

(5) If the information in the comment bubbles is trivial enough that 
we're happy to say that the blind, the disabled and those who avoid 
Javascript don't need it, then perhaps *nobody* needs it.




[*] In my experience, websites tend to fall into two basic categories: 
those that don't work at all without Javascript, and those that run 
better, faster, and with fewer anti-features and inconveniences without 
Javascript.


-- 
Steven