Documenting the Documenter  
Author Message
Bill Blum





PostPosted: Developer Documentation and Help System, Documenting the Documenter Top

I notice that Sandcastle ships without any documentation. I followed the links that promised to answer frequently-asked questions and questions and hints and tips. The questions were obviously being asked by people who had been using Sandcastle and had some kind of detailed question about some operational point or another. How did they find out how to start using it enough to ask a question about features

But I can't even get started. There are three executables in the download: BuildAssembler, MRefBuilder, and XslTransform. When I run MRefBuilder on my assembly, all I get is an XML file. But if that's all I want, I can get an XML file from Visual Studio by throwing the /doc switch.

When I run BuildAssembler, I get a message: "Error: The specified configuration file could not be loaded. The error message is: "Could not find file 'C:\Program Files\Sandcastle\ProductionTools\BuildAssembler.exe.config'." Well, that does not help me run the program because I don't have a configuration file, I don't know how to make a configuration file, and no configuration file was installed with SandCastle.

XslTransform apparently wants an XML file and an XSL transform file. Is that supposed to be the output of MRefBuilder and some as yet unidentified transform file One does not know because nobody thinks it necessary to explain. Do I have to write my own XSL transform file Probably not.

But the point is: none of the questions in the FAQ ask how to run the program, and none of the links on the installation page point to anything but broken wikis and FAQs for more advanced users. How does one get started



Visual Studio28  
 
 
EWoodruff





PostPosted: Developer Documentation and Help System, Documenting the Documenter Top

Most of the How To information is in some of the older blog posts. The most important one if you need to know how to run the tools in sequence to produce a help file can be found here: http://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

If you are familiar with NDoc or would prefer a more automated approach to managing and building the help files with Sandcastle, you can download the Sandcastle Help File Builder from here: http://www.codeplex.com/SHFB. See the Getting Started section and the FAQ in the help file which covers most of the common questions about using it.

Eric


 
 
Bill Blum





PostPosted: Developer Documentation and Help System, Documenting the Documenter Top

Thanks, Eric, this is exactly the information I needed.