[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
steve at pearwood.info
Sat Nov 27 23:11:44 CET 2010
Nick Coghlan wrote:
> On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl at gmx.net> wrote:
>> at <http://dpo.gbrandl.de/contents>, you can look at a version of the 3.2
> 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.
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
[*] In my experience, websites tend to fall into two basic categories:
better, faster, and with fewer anti-features and inconveniences without
More information about the Doc-SIG