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.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Is Sandcastle any better for conceptual topics?: From: Paul Goble
Re: Is Sandcastle any better for conceptual topics?: From: Bill Swallow

Previous by Author: Is Sandcastle any better for conceptual topics?
Next by Author: RE: Real World Advantages of Office / Word 2007 and Windows 7
Previous by Thread: Re: Is Sandcastle any better for conceptual topics?
Next by Thread: Greetings - Looking for a little advice please.


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


Sponsored Ads