locked
What help format to use RRS feed

  • Question

  • Should developers be authoring help  for user guides, libraries etc in compiled help format or should they be using Microoft Help 2.x?

    My primary concern here is authoring for Vista, not XP and below.
    What doesn't kill you, defines you!
    Wednesday, September 17, 2008 11:51 PM

Answers

  • Hello Taime,

    you know, Chris said it "Use Help 2.x only for products that extend Visual Studio (because VS itself uses Help 2.x), use HTML Help for everything else.". This is recommended by Microsoft at this stage too.

    AP Help 1.0 (Assistance Platform Help) is the generation of online Help being developed for and shipped with Windows Vista and based on Microsoft AML (formerly MAML) It will not be made publicly available as an authoring platform for other software vendors. It will be used by Microsoft, OEMs, and certain corporations.

    IMHO problem today is that many things out there and we have the problem to choose. Try googling for DITA, DocBook ..
    AML is one more XML-based format you *can* use but it's not well documented by Microsoft.

    Sandcastle as a more "developer preference" has some Microsoft AML documentation now. Please see:
    http://en.wikipedia.org/wiki/Sandcastle_(software)
    http://www.codeplex.com/SandcastleStyles
    http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

    You may be interested how to show CHM's by API calls from Visual Studio (search for ClickOnce example) from:
    http://www.help-info.de/en/Visual_Basic_2005/vb_2005.htm

    To shorten the story
    - use HTMLHelp for user online help (may be in an extended way by transforming XML-based source to HTML files)
    - think about if XML-based source format is necessary for you now (may be by using Sandcastle and using AML "Conceptual help")

    Ulrich







    Ulrich Kulle - Microsoft MVP - Help - http://www.help-info.de
    • Marked as answer by Taime Downe Saturday, September 20, 2008 2:57 PM
    Saturday, September 20, 2008 12:05 PM
  • Hi,

    If you're interested, Sandcastle can produce web-based output as well as compiled help 1.x and 2.x using additional tools.

    Sandcastle also provides first-class support for MAML, so it's certainly not dead anymore, it's just not well documented.  Although, there's a basic MAML guide available at the Sandcastle Styles project to get you started.  I highly recommend authoring topics in MAML over HTML.

    Tools that automate Sandcastle, such as DocProject and the Sandcastle Help File Builder also have a web output option and first-class support for MAML.  They also provide additional features and user interfaces that make working with Sandcastle much easier.

    You can find more information about Sandcastle and related tools here.

    - Dave
    http://davesexton.com/blog
    • Marked as answer by Taime Downe Saturday, September 20, 2008 2:57 PM
    Saturday, September 20, 2008 1:31 PM

All replies

  • Since Microsoft still doesn't offer a general-purpose Help 2.x viewer there's little to choose here.  Use Help 2.x only for products that extend Visual Studio (because VS itself uses Help 2.x), use HTML Help for everything else.
    Thursday, September 18, 2008 7:44 AM
  • Hi,

    Don't forget that you also have the option of web help.  If you're building HTML help then there's no reason that it has to be compiled into a distributable file.

    - Dave
    http://davesexton.com/blog
    Thursday, September 18, 2008 2:23 PM
  • I didn't think there would be a general-purpose Help 2.x viewer. But thank you, I now know to carry on with  HTML Help.

    Should we all be embracing MAML? I've seen several posts indicating this is so but I've seen other posts stating MAML is dead. Is there any documentation / SDK for MAML.

    Thanks Dave, I always forget about providing online help, I've just always included the compilation of the help files as a build event in the solution!

    • Edited by Taime Downe Saturday, September 20, 2008 10:21 AM
    Saturday, September 20, 2008 10:19 AM
  • Hello Taime,

    you know, Chris said it "Use Help 2.x only for products that extend Visual Studio (because VS itself uses Help 2.x), use HTML Help for everything else.". This is recommended by Microsoft at this stage too.

    AP Help 1.0 (Assistance Platform Help) is the generation of online Help being developed for and shipped with Windows Vista and based on Microsoft AML (formerly MAML) It will not be made publicly available as an authoring platform for other software vendors. It will be used by Microsoft, OEMs, and certain corporations.

    IMHO problem today is that many things out there and we have the problem to choose. Try googling for DITA, DocBook ..
    AML is one more XML-based format you *can* use but it's not well documented by Microsoft.

    Sandcastle as a more "developer preference" has some Microsoft AML documentation now. Please see:
    http://en.wikipedia.org/wiki/Sandcastle_(software)
    http://www.codeplex.com/SandcastleStyles
    http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

    You may be interested how to show CHM's by API calls from Visual Studio (search for ClickOnce example) from:
    http://www.help-info.de/en/Visual_Basic_2005/vb_2005.htm

    To shorten the story
    - use HTMLHelp for user online help (may be in an extended way by transforming XML-based source to HTML files)
    - think about if XML-based source format is necessary for you now (may be by using Sandcastle and using AML "Conceptual help")

    Ulrich







    Ulrich Kulle - Microsoft MVP - Help - http://www.help-info.de
    • Marked as answer by Taime Downe Saturday, September 20, 2008 2:57 PM
    Saturday, September 20, 2008 12:05 PM
  • Hi,

    If you're interested, Sandcastle can produce web-based output as well as compiled help 1.x and 2.x using additional tools.

    Sandcastle also provides first-class support for MAML, so it's certainly not dead anymore, it's just not well documented.  Although, there's a basic MAML guide available at the Sandcastle Styles project to get you started.  I highly recommend authoring topics in MAML over HTML.

    Tools that automate Sandcastle, such as DocProject and the Sandcastle Help File Builder also have a web output option and first-class support for MAML.  They also provide additional features and user interfaces that make working with Sandcastle much easier.

    You can find more information about Sandcastle and related tools here.

    - Dave
    http://davesexton.com/blog
    • Marked as answer by Taime Downe Saturday, September 20, 2008 2:57 PM
    Saturday, September 20, 2008 1:31 PM
  • OK brilliant. That answers everything. Thanks
    What doesn't kill you, defines you!
    Saturday, September 20, 2008 2:59 PM