Project Documenting under a deadline

Jeff Klawiter — Mon, 30 Jun 2008 01:57:50 GMT

Documenting code is one of those things that programmers tend to leave out while under a tight dealine or just building a new project. It's one of those things we tend to say, if we have time when we're done we can do it. It can be time consuming and sometimes hard to see the benefit up front. I'm very guilty of poor documentation and commenting. I rarely get to work in a team so I always end up relying on my own memory for what does what and where. Then two years go by and I forget it all.

I have been trying to get better about adding at least XML comments to my classes, methods and properties. The project I am on right now is a rather large project due in less than a month and so far we have a semi-concrete middle layer, a half mocked up front end and a half done back end. We need more than just one or two people on the project and I've been in charge of part of the back end and all of the middle layer. Even though it is taking a bit more time I've been trying to add documentation and actually use Unit Tests for my first time. (that's a whole other entry).

While the built in XML Commenting system C# has is great and can really help a programmer when coding there is little to no good way of taking that and making separate documentation out of it. That and editing it can be a real pain. After pouring over the web for some way of exporting the XML as a CHM or MSDN type library I came across DocProject . This wonderfully free and open source VS 2005/2008 Addin is a godsend on this front. It can create a standalone CHM or give you an MSDN library to integrate with your VS or create a web project that has a decent Ajax interface for browsing the documentation online. All export options can be done at once as well.

DocProject lets you edit every part of the XML Documenation in a rich text editor. While I think the editor could use a bit of work (make it easier for putting code in the Example and other regions code can exist) it does a great job of making it much easier to write the documentation instead of just in code.

DocProject does have a bit of a draw back in it's requirements. To use it you must install Sandcastle, which isn't to large. If you want to output in the new Compiled HTML 2.x format you need to install the VS 2008 SDK. The SDK however is nearly 100MB. Though I'd recommend having it anyway, with it you get the ability to write VS addins and other fun stuff.

I just started using DocProject today, so far I'm impressed and I hope it turns out to be a good addition to the development process of this project. I'm hoping to use DocProject's publish features to put the documentation on a site where other developers for the project will be able to reference. I've found over the years that the projects with the most documentation end up being the easiest to work on.

Where did the time go? - Documentation

Project Documenting under a deadline