We use Sandcastle and Sandcastle Help File Builder (SHFB) to generate the SDK of our project. It's really neat but I always wondered if SHFB could do more. It's GUI has some plugins and properties that I never really explored. Dunno why. Never took the time until last Friday afternoon.
I finally convinced myself that I should click on some of those unknown features. How come it took me so long to do this? SHFB supports MAML, Microsoft new online help technology. In a nutshell, MAML separates the content from the presentation. Technology wise, it means you write conceptual topics in an XML format based on a schema. Then, XSLT is applied to your XML document with the help of the Sandcastle engine. The result is a very nicely formatted Html document. Pretty nice hey!
What is a conceptual topic? Well, it can be a glossary, a whitepaper, a how to, a walktrough, etc. Each topic has its own schema. The neat thing with SHFB is that you can edit your topic and preview it on the fly. Personally, the glossary and walk trough topics are my favourites. SHFB then assembles those topics together and produces a .chm file with all of them. This .chm file can then be called from your application with a help provider.
DocProject does the same thing as SHFB but it embeds itself in VS .NET. I tried it out but it wasn't intuitive. I was lost and didn't know how to produce a conceptual topic on the fly. Thank God DocProject has good documentation on how to get you started. But I was still lost with all those folders created for me in my project. It made me feel like in Visual Studio 6 where all this code was created and I had no idea what it did. And to create your .chm file with DocProject, you have to compile your project. Which is a bit weird if you ask me. And you can't preview it like SHFB. But with all this bitching, I still have to raise my hat to Dave Sexton for managing this project.
Overall, if you are looking for a tool to leverage your documentation, and I'm not talking about the SDK, check out Sandcastle Help Filder Builder, its definitely worth the time.
Oh, and be sure to download the Sandcastle Styles. They are need to have the latest styles when generating conceptual topics.