[Python-Dev] [Preview] Comments and change proposals on documentation (original) (raw)

Georg Brandl g.brandl at gmx.net
Sat Nov 27 23:37:29 CET 2010

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

More information about the Python-Dev mailing list