I Wrote It, Why do I Need to Document It?

Setting Up the Scenario

What .NET developer hasn’t spent countless times writing documentation that quickly becomes outdated with each code revision?

Ok, so you dreaded doing it, but your brand new development project is done and completely documented. It took you twice as long to write all of the documentation for other developers to use but it’s finally done, and it looks great.

Now, fast forward three months… you’ve addressed a steady list of bug reports, new features, and redesign requirements. Everything is closer to production, so timelines were shortened and the pressure to deliver the fixes was on. What does that documentation look like now? How about three years into the project with new features and maintenance?

The point is, in most companies, especially smaller development teams (1?), documentation tends to suffer. What I’ve found as the best way to maintain documentation (for yourself or for others) is to build it directly from the source code using Sandcastle comments and the Sandcastle Help File Builder.

Sandcastle Comments and Visual Studio

If you’re not familiar with Sandcastle comments, they’re extremely easy and integrated directly into Visual Studio already. To begin adding Sandcastle comments first ensure XML documentation is turned on for the project by rightclicking on your project, selecting Properties, clicking the Build tab and checking XML documentation underneath Output. Now position your cursor above any function, method, class, or property and type /// (C#) or ”’ (VB). Visual Studio will automatically generate a comment structure for the code object.

Functions and methods with parameters will generate stubs for details about the parameters. The more descriptive you are with your comments, the better your documentation will be. This is the most important aspect of documentation, completeness.

Autogenerating Documentation

Now that you’re familiar with Sandcastle commments and know how to decorate your entire project, we can move onto the real meat of this post which is autogenerating documentation for yourself and others to use.

You’ll want to begin by downloading two projects from Codeplex to make extraction and formatting of the comments much easier; these are the Sandcastle Project and the Sandcastle Help File Builder.

Once installed, open Sandcastle Help File Builder, and select New Project. Name the project, and once it finishes startup, right click on Documentation Sources, select a Visual Studio Project or Solution. You can set many different options here or simply click Build. Just like that, you’ve created a .CHM help file. Not impressed? Let’s go one step further and create MSDN-style web-based documentation by simply selecting Help1xAndWebsite under the HelpFileFormat dropdown. Point to an output directory and you’ve got your own min-MSDN.

Additional Benefits

One of the great things about documentation in this way is that it ties your documentation closely to your code. As you change code, your documentation can be easily updated because it intuitively describes the code you are currently updating. Another advantage is to change Visual Studio to treat undocumented code as errors/warnings; this forces you to do the extra work of documentation which you may thank yourself later for.

Hopefully this helps documenting your next project. Happy coding!

*Special thanks to Ben Lawrence for first introducing me to this great codeplex project!