Creating Help documents for web and desktop applications.

By Mirek on 10/14/2011 (tags: Help content, categories: infrastructure)

During software application development there is always a moment when user manual an help content must be written. Choosing appropriate tool for that is very important and decides about help creating and updating process speed. Help format is as important as the help itself and must be easily accessible from the application and convenient for the end user.

There are few help format that are worth to be considered:

CHM files – Windows Help document viewed with help viewer built in system
PDF files – forces user to have appropriate reader installed, open help document and searching for appropriate topic
DOC files – same as for PDF
HTML based help format
MSHC - Microsoft Help Viewer 1.0 MSDN like help format

Both PDF and DOC files can be used for either desktop or web application. These does not offer any kind of application integration. Are useful as a user general manual.

The chm format help is very popular for desktop based applications. It is convenient and may be dynamically linked with an application gui to display specified topics. Although it is based on html pages is useless in web application since compiled in one .chm file can be only downloaded as a single file and viewed on client computer.

On the other hand there is a web based help content. The msdn knowledge base is a good example of such help format. It can be accessible and integrated from either desktop or web application. Undeniable advantage of web based help is that it is always up to date and need to be updated in only one place to be available for all clients.

Microsoft Help Viewer 1.0 is quite new help format introduced by Microsoft as a replacement for Microsoft Help 2 format. This is a common help used in Visual Studio 2010. MSHC file is a zip file containing help content in html format with some special conditions.

To create an maintain the help content it is convenient to use help authoring tool. This is an application that facilitates creating the help content and usually allows to export to many formats. There are many help authoring tools available on the market.

HTML Help Workshop – Microsoft
licence: freeware
output formats: CHM
difficult to use
webpage: HTML Help Workshop
HelpNDoc
licence: free for non comercial use, 139$ to buy
output formats: CHM, HTML, PDF, DOC
easy to use, intuitive interface
webpage: HelpNDoc

HelpNDoc – Html output help document
HelpStudio 2011 – Innovsys
licence: 486$ to buy
output formats: web, chm, pdf, Microsoft help viewer 1.0 MSHC
many options, quite easy and intuitive
webpage: HelpStudio 2011