Ian Bicking: the old part of his blog

Doc Comments

After reading a post by Titus Brown I got to thinking about documentation and comments again. People constantly ask that Python documentation have a comment system similar to PHP's. It's also a recurring theme for myself, and I have long meant to write something for collecting such comments; in fact the first web application of any size that I wrote was a system for collecting comments from article contributors at a publishing house.

Anyway, I've always been frustrated by the UI available for comments. My original app stuck little links at the end of every sentence -- useful for that situation, but rather intrusive. Ka-Ping Yee's crit.org (a site which passed away, the domain now reused for something unrelated) had the user select text and used simple text matching to determine where to insert the comment. Backtalk uses quite intrusive links. So last time around I got kind of discouraged by this form of interaction. I don't know what the state of the art is these days, but it wasn't that great at the time.

But we're in this new Ajax world now (where Ajax can primarily be read to mean "Javascript now works") and I thought I should give it another go. A week later, after some manic coding and mostly ignoring my other projects, I have an app...

The app is called Commentary. You double-click on an element to leave a comment on it. Right now I want to focus purely on the use case of leaving comments on technical documentation. Based on this it writes to simple flat files which can be committed to a repository and edited both on- and off-line.

Besides the Commentary site itself, you can also comment on the SQLObject site including of course its documentation. I welcome feedback, particularly in the form of tickets.

Note: it doesn't work entirely in IE yet. Edit links for one don't work. I don't know why; I'm not getting any exception, but when I access req.responseText it just stops, without any exception. Ideas on what's going on are welcome.

Created 07 Dec '05
Modified 07 Dec '05


Typo in the URL your "Commentary" link, the N and O are swapped in python.

# Joe W.

This is a very encouraging implementation of a great idea. It's got a few bugs with setting the background color of an element to white when you start and cancel a comment - try commenting on a code snippet, or on the definitions followed by the dictionary terms.

What I'm really interested in seeing is something like this for a trac changeset in order to facilitate distributed (post-checkin) code reviews. How hard would it be to hook line numbers (or ranges) instead of element-ids?

# Michael Urman

You should be able to comment on any block-level element. So if each line is a block level element, then you'd be set. They probably aren't block level elements, though. The comments use a Very Little Language to identify what element they were attached to, anchored on something that can be found globally and hopefully is stable (typically an element with an id). Right now when you double click it walks up the DOM tree to the first block-level element it can find; potentially that could be configurable so you could comment on smaller elements.

Another option would be for the path language to know about named anchors too (I've meant to add this anyway), and for it to also stop on named anchors even if it is looking for a block-level element. And then, if you put a named anchor in every line of your code (nice anyway) it can be commented on that way.

I've actually also thought about Trac as well, as this seems relevent to a lot of what Trac does. So I definitely hope they can work together in some fashion.

# Ian Bicking

What a great idea whos time has come, and a pretty good implimentation. I've started putting in some comments in the SQLObject docs in areas that are confusing to me.

# Mike Kent


recently Phil added doc comments to the pygame.org site api reference.

It has turned out to be quite good. However we try and remove those comments and fix up the original documentation instead of leaving the user comments in there. It has been a good way to collect bugs. Especially documentation bugs.

Every week or so I go through all of the new comments and try and integrate them into the documentation.

I highly reccommend that you make a list of new comments available for you to see as a list, so that you can use it as a bug catcher. As well as use it to quickly review the submitted notes.

Another difference is that we hide user comments until people click on a link to show them. We think this reduces clutter on the page.

Also we use a wiki for non api documentation. The reason we don't use a wiki for api reference is that the api reference is generated from the code, and having the wiki as the master source for documentation was not seen as being very useful.


# Rene Dudfield

This is definitely meant for that same kind of workflow. The comments are written to flat files that can be edited by hand, so you don't have to manage them through the website (since presumably you don't manage your documentation through the website). Also, they try to keep the same layout as the documentation they are being applied to. E.g., comments to /index.html go into /index.comment.txt (at least that's how I've configured these instances). Lastly, they are committed to Subversion, possibly right into your documentation directory (again, that's how I've configured these instances); history is preserved and notifications can be run off that. And the comments themselves, though they aren't inlined into the original source, do use a position identifier that is supposed to be more-or-less human readable (I'm hoping in particular that it will work well with documentation generated from restructured text). And I plan to make the comments themselves reST, so that documentation can just be moved over verbatim from comments. For generated documentation (like API reference) the source and comments won't be living quite as closely to each other, but so long as the paths match the source in some sensible way it shouldn't be a problem.

If there was a good Javascript text editor (which there seems not to be) I hope this can be a source of substantive documentation contributions.

As for the display, I'm not sure. I think by floating the comments to the right they are much less intrusive than full inline comments are. I think I'll leave them in and work on making them less intrusive (e.g., long comments might be semi-collapsed).

Recipes are another important contribution I want to get more of, but exactly how this all fits with that I'm not sure. Probably people will start submitting them, and we'll see how it goes from there.

# Ian Bicking

I saw that delete button and thought, hmm wonder if that deletes the comment instantly. Then I tried it, and apparently, it does. I think you need to find a way to make surepeople can't delete others comments. And having a waring before deletion would definately not hurt either...

# Sebastian

Yeah, people are deleting things like there's no tomorrow. Definitely confirmation is needed. History is preserved (though not accessible through the website), so comments aren't lost forever; given that I think I'll leave deletes with the same permissions as comments and edits (which might all eventually go behind authentication, but are all open now).

# Ian Bicking