waffle

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.

One of the things that scare me greatly about the current generation of development tools are how many of them are dedicated to generating completely useless, documentation-looking, tautological, disk space-wasting output that would never be of any significant help to anyone.

The default output of Doxygen, Javadoc, Headerdoc and Sandcastle — the most popular open cross-platform alternative and the sponsored alternative of the three major next generation platforms — is horrible. Really horrible. What will you see? You’ll see a verbose listing of every single piece of metadata that the generation is able to reassemble, output in several files, with the documentation itself being easily lost in the flotsam. Some are clearly worse offenders than others; Javadoc’s signal-to-noise ratio is quite good. But I wouldn’t call this documentation.

This isn’t what disturbs me most. The default setting needs to be good, but if it’s not, at least we can work around it, right? Look at the options afforded by most of these tools. You can change the font size and the base path, even the filename format. And you can apply a new coat of paint. But what you can’t do, effectively, is choose how you want to structure your documentation.

You can’t choose which way you’d list the methods. You can’t group several related classes together under hierachial sections. It’s even hard in some cases to find an appropriate lookup table to be able to link to system API type definitions. And forget about including what Apple calls “guides” - prose content explaining the concepts and describing how to use a group of classes. Doxygen lets you create pages, but that’s just a small first step - there’s no sense of hierarchy, no index, no TOC. It’s just hard to do well.

I might not be so peeved by this if it wasn’t that there’s no good niche tools to fill this gap that I’ve been able to find. What most documentation generators provide at the end of the day is nothing more than what you’ll be able to find in any competent IDE, and they don’t even generate that nicely. But hey, you can get it in #FF00FF Comic Sans, and we can render it to a PDF, and if you spend twenty minutes recompiling everything and passing a lot of bullshit to ./configure, we can also draw UML diagrams and retroactively legitimize your work as structured and well thought-out to nosy bosses.

It’s a testament to the sad state of programming that this problem isn’t better solved. Concurrency, scalability, dynamic programming with IDE support — those problems are hard. But this one’s easy. It just takes effort, and for some reason we’ve stopped just clear of a good solution, or we’ve rolled it into some big in-house system that only runs on Ubuntu Feisty after a four hour configuration session and that’s too ugly to let out anyway.

Mega Man 9, it must be said, is not an 8-bit game.

It is comprised of three components:

• An awesome game using the graphics style and control style of the NES Mega Man games.
• A current-generation style infrastructure with downloadable contentcheats whose acquisition require Wii/Microsoft/Whatever Sony Uses Point deduction; and achievements.
• An unusually complex Mega Man menu and navigation shell, also in the style of the NES Mega Man shells.

There are even elements in the game that are very similar in spirit to latter Mega Man games.

None of this is criticism; it’s clarification. We already know that the game is far too big to fit on a NES cartridge. Mega Man 9 is about combining the style of the NES games and, with the exception of the graphics, unshackle them from the technical requirements of the NES. This has succeeded, and I believe the game is better for it.

And in case you couldn’t tell, this is the most fun I’ve had with a game since Portal. Engaging and hard gameplay is just one thing you can achieve if you put the blood, guts and pretty graphics away.

What a first night. I missed the little bugger. So far it’s not much longer, but it is much harder than I thought it’d be, and I’d like to think I have some experience with the predecessors. I planned on taking a lot more time, but it was just too hard. I’m spent already, although it’s been a while. I’ll resume tomorrow and continue the fun all weekend… this thing definitely has staying power, and if you can just perform the right maneuvers, there’s a lot more to achieve.