Quick Sniffcheck - Can I use Sandcastle?

Feb 7, 2008 at 12:47 AM
Before I do a bunch of reading, installs, and testing, could you all please tell me if Sandcastle (and any combination of tools / add-ons that you know of) can:

  • Create the Class / Method documentation from C# code and output either a CHM, or a web site?
  • Integrate conceptual and expository pages into the above with integrated navigation and TOC?
  • Regarding the conceptual stuff above, can it be edited in a VS editor (so dev's can edit without having to leave VS)?
  • Create a new doc set with each build (integrated into the build process / command line interfaces)?
  • End up simple enough that a dev team without a full-time writer can manage the build process and keep things up to date?

I'm sure there'll be other things as I go along, but how about it? Is Sandcastle (and tools) my silver bullet?

Thanks in advance! Keith
Feb 7, 2008 at 1:19 AM
Hi Keith,


Create the Class / Method documentation from C# code and output either a CHM, or a web site?

Sandcastle can generate HTML topics or .ASPX web pages and a basic ASP.NET website. Sandcastle Help File Builder can build an HTML-based website. I'm not sure if it can build an ASP.NET site though. DocProject comes with an ASP.NET Web Application template, called a DocSite.

You can produce a .CHM from Sandcastle's output, but you must install the HTML Help Workshop program first. DocProject or SHFB can be used to automate the process.


Integrate conceptual and expository pages into the above with integrated navigation and TOC?

Sandcastle supports MAML markup for conceptual documentation, but you can also include your own HTML topics if you'd like with a bit more effort. SHFB provides functionality out-of-the-box for including additional HTML content, I'm not sure about MAML though. The next release of DocProject will have first-class support for MAML documentation, but does not currently provide first-class support for including additional HTML topics, although it's possible.


Regarding the conceptual stuff above, can it be edited in a VS editor (so dev's can edit without having to leave VS)?

Yes, help is text-based. If you're adding custom HTML topics then you can edit them in VS using its HTML editor. Same if you're creating MAML documentation; although, the XML editor is used in that case, with IntelliSense support for MAML schemas if you want (DocProject provides this functionality in the next release.)


Create a new doc set with each build (integrated into the build process / command line interfaces)?

Sandcastle can be used on the command-line or with MSBuild on a build server. SHFB supports a console-mode that can be used in the same way. DocProject uses MSBuild templates and the projects can also be built in VS (they're actually VS project templates).


End up simple enough that a dev team without a full-time writer can manage the build process and keep things up to date?

Yes, I think Sandcastle has reached that point. You'll probably want to use DocProject or SHFB though to manage your content/settings and to automate the build process.

- Dave
Editor
Feb 7, 2008 at 3:15 AM
To expand on what Dave mentioned:

SHFB can produce a a Help 1 file (CHM), Help 2 file (HXS), a website, or a combination of the three. For the website, it includes a basic Index.html page as well as an basic Index.aspx page. The ASPX page can perform basic searches on the content. DocProject has a more extensive ASP.NET website project.

Regarding additional content, SHFB has extensive support for it. You can either add the additional content as HTML pages or you can create XML files (using a .topic extension) that will get transformed using XSL so that they look and feel like the API topics in the selected presentation style. Basic transformation files are supplied or you can create and specify your own. The TOC can be controlled automatically based on the file structure of the additional content or you can supply a sitemap file that defines the content and TOC layout. It also supports colorizing code in <pre> tags, importing and colorizing code from external files, resolving links to API topics, and several other features.

It doesn't support MAML documentation yet but I may add that to a future release.

Eric
Feb 7, 2008 at 3:31 AM
Excellent - it looks like it's time to roll up my sleeves. I'm sure I'll have many more questions as I go along!

Thanks to you both for the great feedback.

Keith

PS - (If anybody checks this again, I ashamed to say I don't have a clue what MAML is about. Some publishing XML extension?)
Feb 7, 2008 at 8:13 AM
Hi Keith,

I probably should also mention that DocProject supports building various output types (such as .CHM, .HxS, or proprietary) and provides a high level of extensibility, programmatic and configuration-based, providing complete control over every aspect of DocProject - see About DocProject. (I believe that SHFB is extensible too and supports plug-ins that allow you to generate different types of output.)

Adding custom HTML topics is also possible in DocProject, but it's not recommended (which is why I never added first-class support) because you have to define your own HTML template that looks sort of like Sandcastle's content (DocProject doesn't supply one). Sandcastle's built-in support for generating conceptual content is a better choice, if you didn't already write hundreds of HTML topics, because you can inherently leverage Sandcastle features like expandable document sections and build component processing, without having to code or maintain it yourself (and neither do I :). The benefit being that if Microsoft changes Sandcastle's various presentation styles or creates new ones, they'll also update the conceptual transformations, presumably. Your conceptual documentation will always look like and behave like reference documentation.

Sandcastle provides a Build Assembler configuration file, XSL transformations and shared content data that's specific to building conceptual content with MAML, so it looks just like reference documentation and provides the same flexibility in terms of process; e.g., build components and XSL transformations. You can even add links between conceptual documentation and reference documentation.

MAML is an XML documentation format, like XML documentation in code comments however much more extensive, defining schemas for various conceptual content document types such as How To, Overview, Glossary, and several others. It allows you to write your documentation using structured authoring semantics instead of format and display semantics like HTML; although, even in HTML there's a choice between the <b> element and the <strong> element, the former describing the display style and the latter describing importance, which may be displayed however a browser is configured to display important elements - bold, italic, red, green, etc. (MAML doesn't have any tags that are like HTML though, AFAIK.) It also supports XML Linking and provides various mechanisms for describing documentation and metadata, allowing you to avoid the mixing of formatting and structure in favor of: author documentation now, format later.

For an overview and some background information:
Microsoft Assistance Markup Language

For comprehensive information about MAML schemas with examples:
MAML - Microsoft Assistance Markup Language

- Dave
Feb 7, 2008 at 8:39 AM

fnameKeith wrote:
PS - (If anybody checks this again, I ashamed to say I don't have a clue what MAML is about. Some publishing XML extension?)


I have an article on CodeProject to get you started with Conceptual Help. It gives you information about what works and how.
It also provides a "hack" documentation of the MAML schema.

It is here http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

I think it is about time I give that a real project and get the fun up.
I will create a CodePlex project soon - stay tuned!

Best regards,
Paul.