documen-tedious

We use a wiki for our project management and documentation at work; it fills the role fairly well, and is in principle pretty agile and can be easily changed. In principle.

In practice, editing the wiki is perhaps the most tedious documentation work I've ever done. It isn't the sort of download-and-fill-out-the-template documentation that was so prevalent back in the JDE days--no, this is a continuous, constantly impending job of having to go through the free-form wiki, wrangle it into some sort of organized form, and update the appropriate pages, which may or may not still be linked in the right way. The wiki we're using (Trac) doesn't allow for spaces in the names, so page names aren't exactly English, which makes it harder to link the pages together in the ways I would like; it interrupts my flow to have to redirect and name the links with the built-in wiki formatting rules.

All in all, I'm not too pleased with it. As important as I think documentation is, it should be like an extension of the project, not an entirely new project all its own. Developers are already basically trained to always put in detailed log messages in their commits (at least, we are around here), so why can't the documentation be like that? Granted, we've already got some sort of bastardized Javadoc going on (which doesn't work well; our JavaScript is formatted differently than the generator expects) but that doesn't (and as far as I'm concerned shouldn't) explain the logic, the business rules, the connections to other components, etc. The Javadoc is for the API--what goes in, what comes out, which functions the object has--but not the purpose in the greater project. That's the sort of thing that should be first determined in the design, documented as such, and then updated with implementation-specific comments that change as the implementing class changes.

So, here's my idea for a solution:

• The documentation should stored in a wiki, which should be filled out with the initial design descriptions.
  
• The pages of the design wiki (through macros or something) could be linked to files/classes in the repository which represent the implementation of that design element, which will have their API reference generated directly from comments in the code (Javadoc, or something)
• The wiki could then be updated by a script/macro that reads markup entered by the developers as part of their commit logs any time a change is made that effects part of the documentation.

It's that last point that I think is lacking in the tech world right now; I think that could be a great open-source project, as well. It should be fairly straight forward, depending on what interfaces exist with the wiki software, and some extension of XML could be defined as the markup for the logs. The programmer could either enter the markup manually, or it should be fairly simple to write a little GUI that would generate it for him or her. Conceivably, it could even download the appropriate wiki page, render it, and allow for editing right in the commit window.

In any case, I wish I had something like that; it would improve our documentation and (as far as I can guess) would not slow us down much in development. Plus, with its similarity to the commit logs, it would be easy to accomplish the required social engineering to get everyone to actually document their changes. I don't really have the time to develop it right now, but maybe someday...