Is Sandcastle any better for conceptual topics?

Subject: Is Sandcastle any better for conceptual topics?
From: Paul Goble <pgcommunication -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 21 May 2012 13:39:16 -0500

A few years ago, the accepted wisdom was that MAML wasn't documented
anywhere, and partly for that reason, it was rather difficult to
incorporate conceptual topics in Sandcastle. I noticed that the current
version of the Sandcastle Help File Builder (SHFB) includes what appears to
be adequate documentation for MAML. Or maybe that documentation has been
there for a while, and I just haven't had occasion to notice it. Have any
of you used the SHFB and associated MAML documentation recently? Has it
improved to become a solution worth considering?

For the rather modest but continually changing API I'm documenting, I don't
want to invest much time in tweaking the SHFB-produced HTML Help, or to
invest much money in a paid-for tool chain. My fallback strategy will be
to author the conceptual stuff as HTML Help in Flare, and do a simple
run-time merge with the Sandcastle CHM file. In that case, my worry will be
how to keep hyperlinks to specific topics in the CHM file from breaking.

For those who are baffled by my jargon:
* Sandcastle = Software which takes specially-formatted comments embedded
in the source code of programs written with Microsoft Visual Studio and
spits out XML-formatted documentation. Much like Doxygen, if you've heard
of that.
* SHFB = Additional software that transforms the Sandcastle output into
more-usable formats such as HTML Help.
* MAML = Microsoft Assistance Markup Language, used to format help for
Windows Vista and for Microsoft's software development documentation. SHFB
claims to be able to incorporate MAML-formatted topics into the help files
it generates.

Paul Goble

Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Previous by Author: "comprises" alternatives - "consists of" vs. "includes"
Next by Author: Re: Is Sandcastle any better for conceptual topics?
Previous by Thread: RE: Images pasted from Excel won't print from Word
Next by Thread: Re: Is Sandcastle any better for conceptual topics?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads