Now that we’ve established how code documentation sucks, let’s start by deducing how code documentation could be made great.
The first thing we do is we kill the idea of documenting the API inline with the code. Yes. I’m serious. I know the allure of this. But I also know how it’s holding back documentation.
Here’s what it means:
You have to make your way around bigger files when editing either code or documentation. The other content is a nuisance. Yes, in competent editors you can “fold” those blocks; not an excuse.
Plain-text formatting doesn’t play well with comments, especially multiline comments, code formatting standards, and indent depths where this plays a role.
Documentation copy editing bloats the file versioning history.
It is work to figure out which methods (every method has code; some have documentation) are documented. With creative header file use, this is less of a problem in some languages.
The second thing we do is we integrate code documentation into our IDE with editor integration but without embedding the documentation into the code. Imagine a button in the breakpoint/line number/warning gutter for creating an entry. This is a shortcut to a new documentation panel with a dedicated editor (maybe even a limited form of rich text) with capabilities to add cross references to other methods or types.
From this panel, you can arrange a bunch of topics in a hierarchy, including on which page the documentation for these types go, with a sensible default of one type per page. And of course you can create conceptual material and relate back and forward between that and code elements. (This is Wiki-like, but you control the hierarchal structure, you get things generated for you in a smart way and code elements are handled in a block-wise fashion.) Everything is stored in a plain format, and can be generated into a HTML web site, zip, maybe PDF or in a form suited for the IDE’s documentation browser. And of course, the documentation is (generation or not) shown in your IntelliSense or your Research Assistant or your generic contextual what-have-you as you browse code.
As relieving as it was, whiningventing about how the code documentation generators of today, er, yesterday worked is not going to solve anything. Presenting a clear idea of a more bearable way to document is much more like it; perhaps you’ll now see what I’m getting at.
I like this idea. Reminds me of layers for code, but with documentation as the “crosscutting concern” (shrug). In a way I’m curious what a line-number tagged approach would yield (integrated with the versioning system, so the line numbers stay up to date). Because then it could be language independent and be used for, possibly, lots of things. On the other hand that is very gadgety and comes close to requiring editor support. Plain text 4ever!
By n8 · 2008.09.30 23:33
I didn’t mean for line-number tagging to be part of the “hook”, just for a button in the breakpoint gutter to be a way to bring up the panel with the line’s method already selected and filled in. Things with buttons in this gutter also usually
are spongeworthyqualify for scroll bar “tick marks”, which is another boon.I’d likely pair the documentation to the selector or method signature. The .NET XML comment concoction, for all of its flaws (yes, something of vital importance for me when I write documentation inline with code is to manually escape angle brackets and ampersands and something I wish other schemes would have me do as well; if I rolled my eyes harder right now I’m afraid I might fling them across the room and break something), at least generates a sensible footprint for each type or member, which is just the smallest amount of information needed to accurately locate the element again given the assembly and this identifier. That principle’s applicable cross-language so that you can generate the local dialect of that, but it’s not always a pan-language solution since the “least amount of information” will vary tremendously given generics support, overloads, optional parameters, default values, etc.
By Jesper · 2008.09.30 23:48