Ian Bicking: the old part of his blog

Doc comments comment 000

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.

Comment on Re: Doc Comments
by Ian Bicking