[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
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 Doc-SIG
mailing list