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

Steven D'Aprano steve at pearwood.info
Sun Nov 28 00:58:52 CET 2010

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

More information about the Python-Dev mailing list