[Pydotorg-redesign] User comments on python.org

[amk at amk.ca ()]

[This message has also been posted to comp.lang.python.]
On Fri, 10 Oct 2003 12:58:49 GMT,

they're referring to the .net rather than the .org site. "Annotatable"
docs (perhaps with some overview) sure sounds like a way-cool idea, but
I have no first-hand experience of how well it works in practice.

Well, let's get some experience. python.org already has a Wiki, so we have
a facility for editing text. It would be straightforward to have a
"View/Edit comments" link on each page that directed the user to a
corresponding Wiki page, perhaps popping it up in a separate window.

Questions:

* Including comments in the page is difficult; I looked at modifying
MoinMoin to do this, but it's not easy. So how can the link be made fairly
obvious? Links at the bottom of page aren't very obvious. A sidebar link
perhaps? (Even if we don't do annotation for the current site design, it
might be worth coming up with a good indicator for the redesigned version.)

* Should comment links be on every single page, or should they just be
limited to certain sections, such as /doc/current/?

* Does the Wiki stylesheet need to be tweaked for this use? (Perhaps by
suppressing the sidebar, for a start. Pity, after Jurgen went to all that
effort to put it there.)

--amk

[amk at amk.ca ()]

[This message has also been posted.]
[CC'ing to pydotorg-redesign, and setting followups there, too.]

On Sat, 11 Oct 2003 19:19:41 -0500,

I don't really know how the Python site is set up now, but could
comments be included inline as an SSI? Like

I don't think SSIs are currently enabled, but it wouldn't be hard to turn
them on. However, I have two worries about this:

1) Fitting the comments into the page design -- a page with a lot of
comments would be really, really lengthy.

2) What if people post obscenities or harmful material?
Showing comments by default would be embarrassing; if you have to
explicitly choose to view them, this is less worrying.
Python.org has a really good Google PageRank, I expect, making it
a good target for link spam, so this is something to worry about.

The Wiki has mostly escaped such vandalism; presumably it's unobtrusive
enough that spammers haven't noticed it.

the page content and the barest of controls). I think it would be best
done as a separate wiki, maybe with a namespace that fits the library
documentation structure better. Or maybe both are possible. It would

Perhaps. Wiki names can contain '/', so we can have annotations for every
single page on the site by just using the full path name. The question is
whether we need that level of support; perhaps the docs are the only place
where comments are valuable. I do think that comments on the reference
manual or the Distutils manuals would be useful. (Possibly PEPs, too?)

I did a bit of experimenting with the separate page, adding JavaScript to
ht2html's output and adding an ugly 'view comment' link. If we're
interested in pursuing this, I'm willing to do the following:

1) Make a set of experimental pages with comment links, so we can see
what they look like and how they work in practice.
2) If 1) looks worthwhile, then I'll make a new Wiki for user notes that has
minimal styling.

What I'd really need is presentation suggestions: *how* to show the comment
link?

--amk

[Simon Willison]

Post by amk at amk.ca ()
I don't think SSIs are currently enabled, but it wouldn't be hard to turn
1) Fitting the comments into the page design -- a page with a lot of
comments would be really, really lengthy.

The coolest way of handling this problem I've ever seen is on
www.kuro5hin.org - load up one of their full story links, then select
"dynamic minimal" from the Display menu and hit the "set" button. This
causes all comments attached to an entry to be displayed as just the
title with a blue arrow icon - clicking the icon dynamically loads that
comment without reloading the page.

Despite using some pretty advanced Javascript, the technique works in
both IE and Mozilla. Browsers that do not support the javascript (such
as Opera) can still see the comments, but have to put up with a round
trip to the server when they click on a link.

A less cool solution would be just to paginate the comments.

Post by amk at amk.ca ()
2) What if people post obscenities or harmful material?
Showing comments by default would be embarrassing; if you have to
explicitly choose to view them, this is less worrying.
Python.org has a really good Google PageRank, I expect, making it
a good target for link spam, so this is something to worry about.

The way PHP.net handles this is that ALL comments are placed in a
moderation queue and only appear on the site once they have been
manually approved. This solution would be a disaster if comments were
meant for discussion, but on PHP.net comments are meant as annotations
to the page in question hence it doesn't matter if there is a delay of a
few hours bewteen the comment being posted and it going "live". I would
suggest the same approach for Python.org.

I have to admit, much as I love Wikis I don't see that Wiki style
functionality is the best way to go about adding user comments to pages
of Python.org. Wikis are fantastic tools for fleshing out ideas and
allowing a small group of smart, dedicated people to collaborate. User
comments on a high profile site like Python.org are less of a community
driven thing - people drop in to the site every now and then and maybe
comment on a feature of the language they have just used.

Cheers,

Simon Willison
http://simon.incutio.com/

[Skip Montanaro]

amk> 1) Fitting the comments into the page design -- a page with a lot
amk> of comments would be really, really lengthy.

I would prefer to see a little icon next to paragraphs with comments. That
minimizes the change in length. Click 'em to pop up a window (or something)
with the relevant comments.

amk> 2) What if people post obscenities or harmful material?
...

amk> The Wiki has mostly escaped such vandalism; presumably it's
amk> unobtrusive enough that spammers haven't noticed it.

That and the fact that a few people subscribe to changes to most pages, or
at least to the RecentChanges page, so they are alerted quickly to changes.
Juergen, Guido and I have all reverted Wiki changes. In my experience, most
changes are one of two types:

* Someone tries to slip their website's URL into the Wiki in hopes it
will score higher with more search engines as a result

* Comments like, "Are you aware anyone can change this page? Isn't that
a bug?"

I'd be against anything which actually modified the content of a page as a
result of adding a comment, if for no other reason than it would have to
integrate with ht2html+CVS, at least for the forseeable future.

Skip

[amk at amk.ca ()]

Post by Skip Montanaro
I would prefer to see a little icon next to paragraphs with comments. That
minimizes the change in length. Click 'em to pop up a window (or something)
with the relevant comments.

Too difficult; we'd need a way to identify paragraphs, and then a way to
modify page content to insert the icon. The W3C way would be to use ID
attributes on paragraphs and then use XPath (or just an ID reference), but
there's no way to make that work without server-side processing.

For this reason, the link text would have to be generic, something like
'View/add notes'; we can't have a link that's only there if there's already
a note.

--amk

[Ian Bicking]

Post by amk at amk.ca ()
[CC'ing to pydotorg-redesign, and setting followups there, too.]
On Sat, 11 Oct 2003 19:19:41 -0500,

I don't really know how the Python site is set up now, but could
comments be included inline as an SSI? Like

I don't think SSIs are currently enabled, but it wouldn't be hard to
turn
1) Fitting the comments into the page design -- a page with a lot of
comments would be really, really lengthy.

Sites that have this usually offer versions of the documentation with
and without comments.

I can imagine three places where comments would become excessive -- the
documentation has problems, the domain is inherently confusing or large
(the cgi module turns into a tutorial on CGI), or significant recipes
are included.

These are all basic Wiki refactoring problems -- editing the original
documentation (to make it less ambiguous, so the comments aren't
needed, or otherwise improve it); or creating more documentation
(perhaps linking to other Wiki pages that go on at length on a topic).

Post by amk at amk.ca ()
2) What if people post obscenities or harmful material?
Showing comments by default would be embarrassing; if you have to
explicitly choose to view them, this is less worrying.
Python.org has a really good Google PageRank, I expect, making it
a good target for link spam, so this is something to worry about.

I think it will be better when the comments are included inline,
because many more people will view the comments. The same is true for
general accuracy. Spam and such is best handled on a Wiki when there's
lots of people to fix it. But maybe php.net or other places would have
more experience on this (php.net does put comments at the end of each
page). Maybe user logins are a good way to raising the bar to
discourage useless (or worse) comments.

I also like the idea of using Wiki pages instead of the traditional
appended comments -- I think it would be more constructive.

Post by amk at amk.ca ()
The Wiki has mostly escaped such vandalism; presumably it's unobtrusive
enough that spammers haven't noticed it.

the page content and the barest of controls). I think it would be
best
done as a separate wiki, maybe with a namespace that fits the library
documentation structure better. Or maybe both are possible. It would

Perhaps. Wiki names can contain '/', so we can have annotations for
every
single page on the site by just using the full path name. The
question is
whether we need that level of support; perhaps the docs are the only
place
where comments are valuable. I do think that comments on the reference
manual or the Distutils manuals would be useful. (Possibly PEPs, too?)

There's definitely places besides the library reference that could use
these comments, but I think they could all be listed out explicitly. A
little rewrite magic could keep it in a flat hierarchy.

Post by amk at amk.ca ()
I did a bit of experimenting with the separate page, adding JavaScript
to
ht2html's output and adding an ugly 'view comment' link. If we're
1) Make a set of experimental pages with comment links, so we can see
what they look like and how they work in practice.
2) If 1) looks worthwhile, then I'll make a new Wiki for user notes
that has
minimal styling.
What I'd really need is presentation suggestions: *how* to show the
comment
link?

I think it should *not* be in the sidebar -- the sidebar is
navigational and it's implied that it's specific to the site or
section, not that particular page. But the library reference doesn't
really have a sidebar, so nevermind that...

In the top bar then, by the TOC/modules/index links... or maybe the
arrows, since those are context-sensitive, where the other links are
global. Then maybe a larger link at the bottom of the page (kind of a
further reading link).

If the comments aren't included inline, I feel like it would be
important to indicate if there *were* any comments. It's annoying and
discouraging to be in a site that hints at things that aren't there --
and there will be a lot of "not there" when this feature is first
added. But I think implementing that would be fairly hard to do. But
important. But hard. Sigh.

--
Ian Bicking | ***@colorstudy.com | http://blog.ianbicking.org

[Bengt Richter]

Post by amk at amk.ca ()
[CC'ing to pydotorg-redesign, and setting followups there, too.]

(somehow the email address got into the newsgroup slot for me, so I had to fix it)

Post by amk at amk.ca ()
On Sat, 11 Oct 2003 19:19:41 -0500,

I don't really know how the Python site is set up now, but could
comments be included inline as an SSI? Like

I don't think SSIs are currently enabled, but it wouldn't be hard to turn
1) Fitting the comments into the page design -- a page with a lot of
comments would be really, really lengthy.
2) What if people post obscenities or harmful material?
Showing comments by default would be embarrassing; if you have to
explicitly choose to view them, this is less worrying.
Python.org has a really good Google PageRank, I expect, making it
a good target for link spam, so this is something to worry about.
The Wiki has mostly escaped such vandalism; presumably it's unobtrusive
enough that spammers haven't noticed it.

the page content and the barest of controls). I think it would be best
done as a separate wiki, maybe with a namespace that fits the library
documentation structure better. Or maybe both are possible. It would

Perhaps. Wiki names can contain '/', so we can have annotations for every
single page on the site by just using the full path name. The question is
whether we need that level of support; perhaps the docs are the only place
where comments are valuable. I do think that comments on the reference
manual or the Distutils manuals would be useful. (Possibly PEPs, too?)
I did a bit of experimenting with the separate page, adding JavaScript to
ht2html's output and adding an ugly 'view comment' link. If we're
1) Make a set of experimental pages with comment links, so we can see
what they look like and how they work in practice.
2) If 1) looks worthwhile, then I'll make a new Wiki for user notes that has
minimal styling.
What I'd really need is presentation suggestions: *how* to show the comment
link?

Have a look at

http://www.xml.com/axml/testaxml.htm

for a way of associating commentary with (it says, at least) unchanged original matter
(in this case the XML spec). It's pretty easy on the eyes. I don't know the implementation,
but I think that separation of pristine original from comment material would be good. The
above site probably has the advantage of heavy xml tagging in the original that the commentary
database can used for retrieving associated commentary, I would guess.

Since full comment generation for dynamic javascript-controlled interaction is somewhat
computer-costly, caching results of generating responses to comments would make sense,
I think, and I don't think generating it should be the default.

If the python.org server is able to insert an optional footer chunk just before the </html>
when so configured to do it for a directory or a file (I don't know if Apache can do that,
since I just made it up, but ISTM it would be a useful option ;-), then that footer could
contain a link for viewing commentary.

The link would go to a comment-server URL, e.g., commentary.python.org/coments.cgi,
The cgi program will see HTTP_REFERER from the page the user clicked the comments link on,
and it can either get a copy via HTTP, or look it up on the local hard disk if it's local.

The URL can also be used as a key into a database of commentary, where also commenter-accounts
could be maintained to keep out spammers.

With the original page plus a database of commentary, the problem becomes building a new
image of the original with unobtrusive commentary navigation. With javascript you could
do floating hint text from commentary title lines associated with paragraphs or other
elements you were mousing over. Clicking might put the commentary in a separate popup window.
Right clicking on a previous comment might mean pop a form to add your 2 cents. Right
clicking on the main page where no comment hint is being displayed would pop up the
same but with an option to give it a title, since it's new commentary.

All of this is pretty much paragraph oriented. Indexing locations, which have to be w.r.t.
unmarked text in the original can do some kind of soft hash of <p> sections in the original
as indices instead of using line numbers, so the data base can have the hashes as keys, and
not get thrown too much by updates in the original. Actual anchor targets and tag ids
can be used too I suppose (I'm just thinking out loud ;-) Anyway, you get the idea. If it
makes you rich, I want a piece ;-)

my 2 cents ;-)

Regards,
Bengt Richter