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

Don Johnston donjohnston at selfaware.com
Sun Nov 28 05:17:11 CET 2010

Steven D'Aprano <steve pearwood.info> writes:

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.

As an end-user, I, too, share concerns about the accessibility of the pending (proposed?) commenting functionality.

A read-only JSON API would be great.

Up until now, Sphinx has been an incredibly helpful tool for generating beautiful documentation from ReStructuredText, which is great for limiting the risk of malformed input.

The new commenting feature ("dynamic application functionality") requires persistence for user-submitted content. Database persistence is currently implemented with the -excellent- SQLAlchemy ORM.

So, this is a transition from Sphinx being an excellent publishing tool to being a dynamic publishing platform for user-submitted content ("comments"). I am sure this was not without due consideration, and FUD.

The Python Web Framework communities (favorite framework here) will be the first to reiterate the challenges that all web application developers (and commenting API providers) face on a daily basis:

Here are a few scenarios to consider:

(1) Freeloading jackass decides that each paragraph of our documentation would look better with 200 "comments" for viagara. Freeloading jackass is aware of how HTTP GETs work.

(2) Freeloading jackass buys a block of javascript adspace on . The block of javascript surreptitiously posts helpful comments on behalf of unwitting users.

Trying to read through the new source here [1], but there aren't many docstrings and BB doesn't yet support inline commenting. AFAIK, there are not yet any issues filed for these concerns. [2]

  1. In the event that that kind of bug is discovered, how should the community report the issues?
  2. If we have an alternate method of encouraging documentation feedback, how can this feature be turned off?

Thanks again for a great publishing tool, Don

[1] http://bitbucket.org/birkenfeld/sphinx [2] http://bitbucket.org/birkenfeld/sphinx/issues/new

More information about the Python-Dev mailing list