Re: Is Sandcastle any better for conceptual topics?

Subject: Re: Is Sandcastle any better for conceptual topics?
From: Bill Swallow <techcommdood -at- gmail -dot- com>
To: Paul Goble <pgcommunication -at- gmail -dot- com>
Date: Wed, 30 May 2012 11:47:40 -0400

Why would you not add conceptual info to the doc comments in the code?
You're adding overhead by using 2 tools for one output. If your goal
is single-sourcing, then source the content outside of the code and
use a reference in the code to consume the content upon building from

On Mon, May 21, 2012 at 2:39 PM, Paul Goble <pgcommunication -at- gmail -dot- com> wrote:
> 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.

Bill Swallow
Content Solutions Manager
GlobalScript, a division of LinguaLinx

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 @


Is Sandcastle any better for conceptual topics?: From: Paul Goble

Previous by Author: Re: tech writing recruiters
Next by Author: RE: tech writing recruiters
Previous by Thread: Is Sandcastle any better for conceptual topics?
Next by Thread: Re: Is Sandcastle any better for conceptual topics?

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

Sponsored Ads