TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
Sandcastle.
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
