User comments on python.org

[Ian Bicking]

On Tuesday, October 14, 2003, at 02:46 AM, Bengt Richter wrote:
> 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.

That does display quite nicely with the frames.

I wrote a system for doing comments like this some time ago, which was 
usable for people doing a dedicated task (but probably would be 
annoying for a casual reader).  Ka-Ping Yee also wrote something quite 
a while ago (crit.org, which seems to be gone now).  I think he wrote 
it in Perl, so no wonder he didn't keep it maintained and up ;)

I think there's generally two issues with comment systems -- entering 
comments and preserving comments when the underlying document changes.  
The two go together, because the robustness of the attachment of the 
comments is related to how you define the place the comment goes.

Crit, if I remember, attached the comment to a phrase.  You would copy 
a piece of text into the form, and comment on that text.  Then someone 
could view the annotated version of that document, and wherever that 
text appeared your comment would appear (which is hopefully only where 
you meant your comment to appear).  With feedback this could be made 
more reliable, of course.  I don't really like the input mechanism, 
though.

So comments could get lost due to even trivial changes in the text, but 
in reality many comments would be able to persist in their context even 
when the document was restructured significantly.

Another technique -- used by Backtalk (in Zope) is to explicitly define 
comment points.  Several systems I've seen have used this.  Typically 
you have markup in the text (maybe a specially formatted comment), and 
at such a point there'd be a button to add a comment.  I haven't seen a 
Backtalk page I've liked yet, but I think that has a lot to do with the 
finer details of the system -- the graphical design badly needs 
refinement.

The system I made inserted a comment point automatically for each 
sentence.  I was getting editorial feedback, so the exact context was 
more important than aesthetics -- but by using a small but distinct 
marker (on the size of a +) it didn't get in the way too much.  I 
didn't preserve comments over versions, so reliability didn't matter -- 
I suppose you could attach the comment to the preceding sentence 
textually.  I wouldn't want to read that casually, however.

Maybe better (to avoid distracting the casual reader) would be to have 
paragraph-level comment points, and allow the commenter to be more 
exact in a follow-up form if they choose.  But that's very bad for 
reliability, because paragraphs are likely to change in small ways or 
be moved around in different versions of the documentation.

Maybe this could be fixed up manually, or orphaned comments could be 
put at the bottom of the article (presumably to be fixed or deleted at 
some later date).  You could also keep track of what version of the 
document the original comment was attached to, to more easily mark and 
correct comments that may be incorrectly placed for a newer page (but 
until corrected, you could guess based on fuzzy text matches or by 
counting paragraphs).

I do definitely like the way comments are presented in that document -- 
that's definitely better than inline or popup comments.

Seems like a fun project, and something that could potentially be 
implemented on top of the current website without directly changing the 
current site (except adding links to the system when it was completed). 
  The reference documentation, being automatically generated, would also 
be quite parsable... hmm... doesn't seem like a very hard project at 
all.  Hmm...

--
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org