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

Georg Brandl g.brandl at gmx.net
Mon Nov 29 09:52:19 CET 2010

Am 28.11.2010 00:58, schrieb Steven D'Aprano:

Georg Brandl wrote:

Am 27.11.2010 23:11, schrieb Steven D'Aprano:

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? :) Aha! I never would have guessed that the bubbles are clickable -- I thought you just moused-over them and they showed static comments put there by the developers, part of the documentation itself. I didn't realise that it was for users to add spam^W comments to the page. With that perspective, I need to rethink. Yes, I failed to fully read the instructions you sent, or understand them. That's what users do -- they don't read your instructions, and they misunderstand them. If your UI isn't easily discoverable, users will not be able to use it, and will be frustrated and annoyed. The user is always right, even when they're doing it wrong wink

That's right, of course. I really come to the conclusion that having a text link that "looks like" a link, i.e. is underlined, will have a better UI experience (since we cannot put notes "click bubble to comment" everywhere).

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?) Lowering accessibility to parts of the documentation is what I was talking about when I said "actively harmful". But now that I have better understanding of what the comment system is actually for, I have to rethink.

Thanks!

Georg

More information about the Python-Dev mailing list