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

[Georg Brandl]

Am 27.11.2010 23:11, schrieb 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 :)

Yes, I already mentioned that the bubbles could be replaced by text links
if they prove too confusing.

> 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".

Maybe you should have tried the page I recommended as a demo, and where Nick
made his comments? :)

> But it seems to me that comments are superfluous, if not actively harmful:

(I've not read anything about harmful below.  Was that just FUD?)

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

Yes.  There need to be ways for the reader to feed back to the author
what they want to have included.  Currently, this is

I'm all for removing comments with suggestions once they have been
integrated in the main text.

> (2) Discovery is lousy -- not only do you need to be running Javascript, 
> which many people do not for performance, privacy and convenience[*], 

That is not an argument nowadays, seeing how many sites/web applications
require JS.  (Most people who deactivate JS globally maintain a whitelist
anyway, and can easily add docs.python.org to that.)

These comments are an optional feature and therefore do not need to
be accessible for 100% of users.

> 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.

Bubbles are always shown for paragraphs *with* comments.

> (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.

You're making this point just because of the size of the bubbles?  Well,
these users can register on the site and there can be a user preference
to display larger links instead (if we choose to keep the bubbles, anyway.)

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

It will be the same as for other web apps using JavaScript.  Since I'm not
a professional user interface designer, I don't know what screen readers
can and cannot do.

> (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.

Sorry, but that is a nonsensical argument.  Apart from the questionable
notion that anything must be available to everyone to be worth anything,
it also doesn't consider that the comments are not only for fellow users:
as I said above, the comments are designed to be a very quick way to give
feedback to *us* developers.  (This is the reason for the "propose a
change" feature, for example.)

So even if only 30% of all users had access to the comments and could use
that to help us improve the documentation by submitting suggestions and
corrections they never would have bothered registering in the tracker for,
that would be a net gain.

cheers,
Georg