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:Paul Goble <pgcommunication -at- gmail -dot- com> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 30 May 2012 15:17:30 -0500
Bill Swallow asked:
> Why would you not add conceptual info to the doc comments in the code?
My goal is to add a half dozen introductory topics and some short "getting
started" tutorials. I don't see a way to add such information in the code
comments--it would end up buried in some part of the API reference, and
formatting options would be limited. (Or is there a way? I'm just
starting out with Sandcastle.)
Using MAML seems to be the "official" approach and it would let me stay
with a single tool. But I worry that once I commit to it, I'll find that
MAML is still basically undocumented. On the other hand, learning a new
markup language would be fun *if* at long last all the critical information
is out there somewhere.
The 2-tool approach isn't as pretty, but I'm 100% confident that it will
work and that it'll be easy to pass on to another, less-technical writer if
necessary.
(Another terminology note: I don't normally use the word "conceptual" to
describe task-oriented topics such as tutorials, but the Sandcastle world
uses "conceptual" for anything that's not part of the API reference.)
Paul
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
