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.
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.
