Documenting the Imtech SharePoint Enhancement toolkit using Sandcastle

Last week I have started documenting the Imtech SharePoint Enhancement Toolkit. The toolkit consists of a module which increases the performance of Internet-facing web sites built upon SharePoint 2007 and a module which addresses accessibility and standards compliancy related issues - also in SharePoint 2007 based Internet-facing web sites.

Because we are planning to share the toolkit with the community as a part of the ‘Innovation Matters’ program (more about the program coming soon) we’re busy with since a couple of months, I have decided to document the Imtech SharePoint Enhancement Toolkit: not only the way it should be configured and the way it works, but also the source code.

To document the source I have used Sandcastle: a great tool which produces MSDN-like documentation using reflection and XML documentation embedded in the source code. While installing, configuring the tool and setting up the project weren’t that difficult, I have stumbled upon some problems with getting the references to SharePoint types right. Sandcastle allows you to create links to the on-line MSDN documentation to the types from the .NET framework. As SharePoint’s SDK is available at MSDN as well, I have decided to use the same feature to create the MSDN links to the SharePoint types used in our code. I have to admit that I haven’t succeeded on getting the references right: I was half way there but then I got stuck. Luckily two guys were there to help me out: Eric Woodruff (coordinator of the Sandcastle Help File Builder project) and Dave Sexton. Once again guys: thank you for your help! Eventually I got it right and soon you will be able to have a look at the SDK of the Imtech SharePoint Enhancement Toolkit.

Soon I will post a step by step on how to get the references to SharePoint assemblies right in the help files generated by Sandcastle. Because the code you’re writing now seems to be clear and comprehensible it doesn’t mean that it will stay like this over a half year or for anybody else who would have to develop on your code. That’s why documenting your code is very important and it might even help you to optimize it as you will have to think about what the code exactly does and why it does it that way.

Technorati Tags: Software documentation, SharePoint 2007, Tools