This project has moved and is read-only. For the latest updates, please go here.

Conceptual documentation tutorial / walkthrough?

Jan 3, 2013 at 7:59 PM

Hello. Could someone please suggest a good tutorial/walkthrough that introduces how to start creating the conceptual part of my documentation? I have all the API documentation done but I'm at a loss as to how to create the conceptual stuff with MAML + Sandcastle Help File Builder GUI. I saw the Sandcastle MAML guide but it seems to only discuss MAML syntax. I really need something that explains how to add the MAML to my VS2010 project and set it up to work with Sandcastle. Do I just add an empty XML file to the project and start typing? Do I need to configure Sandcastle in some way?

I found this:

but it's ancient. Thank you in advance.

Jan 3, 2013 at 8:37 PM

See the Conceptual Content section of the SHFB help file and its sub-topics.  They describe the conceptual content file types that you can add to the project.  I'll make a note to add a proper walkthrough and see if I can get it in the next release.

To get started, all you need to do is add a Content Layout file to the project and open it for editing.  Add topics to the content layout file as it controls which ones appear in the help file and their layout in the TOC.  When added to the layout file, they are automatically added to the project as well.  You can organize the topics in the project in folders to match the layout file or leave them all in the root of the project if there aren't that many.  I typically organize the project files to match the content layout file so they are easier to locate for editing without having to open the layout file.  The Topic Previewer Window is a big help as it lets you preview the topics while you are developing them without having to build the entire help file.

If you have other questions, feel free to ask.



Jan 3, 2013 at 8:48 PM

Thanks for the quick reply Eric. I'll give it a shot.

Nov 20, 2013 at 9:22 PM
Edited Nov 20, 2013 at 9:23 PM
Eric wrote: I'll make a note to add a proper walkthrough and see if I can get it in the next release.

Hi Eric,
Just curiuous. Is such a walkthrough present in the October 2013 release?
Nov 21, 2013 at 2:19 AM
No, sorry I haven't gotten around to it yet.

Nov 21, 2013 at 2:56 AM
No problem. I followed your suggestion to LKeene and played around with a Content layout file added a topic, etc. The Topic Previewer is very nice (essential, really). I'll keep working through it, looking forward to figuring it all out.
Thanks for the quick reply.