Friday, September 4, 2009

Using Sandcastle as a documentation tool

Recently, we evaluated several documentation tools, like ndoc, doxygen etc. We found that SandCastle (together with SandCastle Help File Builder GUI app - http://shfb.codeplex.com/) is the most appropriate tool for generation of rich documentation to .NET libraries.

It can create HTML DOC 1.1, 2.0 and pure HTML output, and here is an example of our work.

http://corp-web.b2bits.com/fixanet/doc/html/

What bugs we has found
1) When we add a picture to the headers of help content files, some fonts will be smaller then it was supposed. Perhaps the tool adds additional div and corrupts styles somehow
2) Sync topics button doesnt work in FireFox (but it is OK in other browsers)

In generally, it is the best free tool for .NET, I believe, while there are also several commercial tools one may consider - a list of them can be found there http://stackoverflow.com/questions/546053/anyone-using-ndoc-or-a-similar-tool-to-help-with-system-documentation/1200561#1200561