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

[Georg Brandl]

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