Finally, Easy Documentation is Back!

Ages ago, NDoc- a jDoc clone- was the best free .NET documentation-generating application in town.  For various reasons, that project shut down, and Microsoft released it's internal documenting system, Sandcastle, to the public.  However Sandcastle by itself is non-trivial to understand and implement.  It's designed to gen up the entire MSDN documentation site, so it can be overwhelming for creating docs for your small line-of-business app.

Enter Sandcastle Help File Builder.  This gem brings back the simplicity and open source spirit of NDoc, and adds some functionality from Sandcastle to provide a great documenting solution for small or large projects. I'd checked it out in earlier versions, but it's come a long way. It even has a console app, which can easily be integrated into your continuous integration process.   In addition, you can add documents other than the typical xml-doc and build a true compiled help that a developer may actually use.

Here's how we set ours up:

• A solution has a _FileReferences project for file-based dll references and other non-compiled code.  (Build is false for all Build configurations).  This project contains:
  • a Help folder that  contains .htm files and the compiled .chm file
  • a .shfbproj file that manages the documentation project.
• In the .shfbproj:
  • A site map has been added to build the table of contents.  It has nodes pointing to each .htm file.
  • The solutions' projects have been added as Documentation Sources.
• An automated process downloads the solution from source control, checks out the .shfbproj and .chm, runs the console app to generate a new .chm, and checks everything back in.

This way, the documentation is constantly updated and available in source control alongside the project!

Share this post :