Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl@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. A discreet notice at the bottom of the sidebar and/or an explanation at the "Report a Bug" page may cover it I guess.
Please test on a smaller page, such as <http://dpo.gbrandl.de/library/math>, there is currently a speed issue with larger pages. (Helpful tips from JS experts are welcome.)
I gave the JS a fair few comments on the first paragraph to digest. I also put my detailed UI comments there as well (I needed something to write about while testing, so I figured I may as well make it useful to you!)
Other things I have to do before this can go live:
* reuse existing logins from either wiki or tracker?
Tracker sounds like the best bet to me.
Any feedback is appreciated (I'd suggest mailing it to doc-SIG only, to avoid cluttering up python-dev).
My comments may on the math module may give you a chance to see how easy it is to get text out of comments into a form suitable for sending to a mailing list or posting to a tracker issue for further discussion :) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 27.11.2010 13:05, schrieb Nick Coghlan:
On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl@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.
A discreet notice at the bottom of the sidebar and/or an explanation at the "Report a Bug" page may cover it I guess.
Yeah. I'd rather keep links for uncommented paragraphs hidden by default though; the cluttering is greatly reduced that way. One thing we need to decide is whether to keep the icons at all; maybe a text link (see http://book.realworldhaskell.org/read/ for an example) is more obvious.
Please test on a smaller page, such as <http://dpo.gbrandl.de/library/math>, there is currently a speed issue with larger pages. (Helpful tips from JS experts are welcome.)
I gave the JS a fair few comments on the first paragraph to digest. I also put my detailed UI comments there as well (I needed something to write about while testing, so I figured I may as well make it useful to you!)
Thanks! :)
Other things I have to do before this can go live:
* reuse existing logins from either wiki or tracker?
Tracker sounds like the best bet to me.
I'll confer with Martin on this one then. Georg
Nick Coghlan wrote:
On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl@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
participants (3)
-
Georg Brandl -
Nick Coghlan -
Steven D'Aprano