Ian Bicking: the old part of his blog

Re: Doc Comments


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.


Comment on Doc Comments
by 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