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

[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*


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


-- 
Steven