Windows Software Help Files Formats@ Dennis Crane
Are you still wondering which help file format to use for your Windows software? The selection depends on your software and on the information that is in your help files. Each help file format has its own unique features that may be useful in certain situations. Generally, I would recommend that you use different help files for different situations.
HTML (On-line manual): Hypertext Markup Language
The help system may consist of number of HTML pages. Each page is usually devoted to a specific topic and includes cross-links to other HTML pages. Often, there is a table of contents that allows fast navigation across the topic areas. Additionally, pages may contain special navigation links: next page, previous page, indexes, etc.
Usually the HTML help pages are uploaded on the product's Website. Creating online help is preferable if your software is platform independent and users can also read the help file in their Web browsers on any operating system. Storing help files as HTML pages on your web site is also useful if you frequently update your documentation by adding new topics and pages. In this case, users do not have to download the entire help file after each update to their computer.
Moreover, the online help manual which is a part of your website generates a targeted traffic. People can easily find your product because the online help allows your website to be more visible in relevant search results on search engines. The new visitors will consider your products seriously when they see a well made help system. Also, if a first time users experience difficulties with your software and needs technical support, you may easily resolve the issue by referring them to a particular page of your online help. With just one click, the users will see screenshots and explanations which will help them to solve the problem.
CHM (HTML Help): Microsoft Compressed HTML Help
CHM is a help format introduced by Microsoft in 1997. The CHM help file is a set of web pages written in a subset of HTML and compressed together with LZX compression. The CHM file has a hyperlinked table of contents. It may also contain word indexes, and therefore, the CHM format is optimized for reading and searching.
The CHM file seems to be the most convenient way to deliver your software help in a single indexed file together with your program. Through the functions provided by hhctrl.ocx library, you may invoke HTML Help functions from any programming language. This HTMLhelp API allows opening a specific topic within the CHM file. Thus, with the CHM file you can easily implement a context sensitive help functionality in your software application.
For Windows users, this help file can be compiled with the HTML Help Workshop, which is distributed by Microsoft at no charge. Besides the HTML Help Workshop, there are commercial tools for creating CHM files faster and easier.
Although the CHM format was originally invented for the Windows platform, there are some tools which can read and navigate these files (e.g. xCHM, KchmViewer, GnoCHM, Chmox for OS X, or Chamonix for OS X), but they lack the various features of the Microsoft Windows tools.
HLP: Microsoft WinHelp
HLP (Microsoft WinHelp) is a proprietary format for help files that can be displayed by the Microsoft Help browser (winhelp.exe or winhlp32.exe modules). WinHelp 1.0 was introduced by Microsoft in 1990.
The source files require that you compile a .hlp file consisting of one or more Rich Text Format (RTF) documents and a help project file with the extension .hpj, along with any image files (.bmp, .wmf, or .shg) that are used within the Help file. An optional table of contents file with the extension .cnt can also be created for use with the .hlp file. The final help file can be compiled using a WinHelp compiler, which is distributed by Microsoft at no charge or by using a commercial help authoring program.
Although less advanced than the later CHM (Microsoft Compressed HTML Help) format, HLP remains a popular Help platform from the Windows 3.0 platform through to Windows XP. Support of HLP files was removed in Windows Vista; therefore the HLP file format is considered obsolete.
PDF: Portable Document Format
PDF is a document file format created by Adobe Systems in 1993 and is now being prepared for submission as an ISO standard. Each PDF file encapsulates the text, fonts, images, and vector graphics that compose the document. While PDF can describe very simple one page documents, it may also be used for multiple pages, complex documents that use a variety of fonts, graphics, colors, and images.
The PDF help file is preferable for platform independent applications because it is used for representing two-dimensional documents in a device independent and resolution independent fixed-layout format. PDF supports forms, links, and bookmarks that allow easy navigation in the document. Because PDF represents documents as a sequential set of pages, it is convenient for printing. PDF supports encryption and digital rights management restrictions.
You can distribute your PDF help file with your software as well as store it remotely on your website. Web search engines, like Google, may index the text content of the PDF file and it will appear in the relevant search engine results.
There are many programs for creating PDFs, including the PDF printing capability built in to Mac OS X, the multi-platform OpenOffice.org, Microsoft Office 2007 (a free download from Microsoft is required), PDF print drivers for Microsoft Windows, and Adobe Acrobat itself. There is also specialized software for editing PDF help files, e.g. Dr.Explain.
RTF: Rich Text Format & DOC: Microsoft Word
RTF is a proprietary document file format developed by DEC in 1987 for cross-platform document interchange. Then, RTF format was purchased by Microsoft around 1990, who extended the standard. Most text processors are able to read and write RTF documents.
DOC (an abbreviation of 'document') is a Microsoft Word file format. Proprietary DOC files often contain more text formatting information (as well as scripts and 'undo' information) than files using RTF and HTML, but are usually less compatible.
Like PDF, RTF & DOC are good for printing documentation, while they may look slightly different in various readers on different operating systems, specifically graphics and embedded objects. These formats may be less convenient for complex documents with multiple pages and objects because of the significant amount of computer memory consumed while being displayed.
These formats may be created with numerous text editing software programs as well as with specialized help authoring software that supports RTF\DOC output.
TXT: Plain Text File
TXT is a computer file which contains only ordinary textual characters with essentially no formatting. Text file is meant to be read as is. The main disadvantages of using TXT files for help are: no graphics, formatting, or navigation. As a result, TXT is only preferable for short documents like installation and release notes and legal documents. Usually TXT documentation is distributed with simple and relatively small applications, like PDA programs or games. You may create a TXT file in any text editor.
Evaluate how your software can be distributed and how people will use it. Do they need a context help file in the application or will they print out the entire help file and keep the manual on their desk? How often will you update the help file? Is it relatively easy to distribute together with your program files or is it better to store it on the website? Answering these questions will help you decide which format is best.
Often the combination of approaches will work best. You may keep the HTML manual on your website for reference and it may attract people from search engines, distribute the CHM file with the application for context sensitive help, and upload the printable version of the help file in PDF or RTF\DOC format on the public website for those who may want to print out the entire document as a reference.
Dennis Crane, the author of Dr.Explain, specializes in help authoring software development. He is online at http://www.drexplain.com
Article Source: https://www.drexplain.com
You are permitted to reprint this text as long as it includes copyright notice and link to our web site.
- Software Documentation in Scrum Projects
- Error Accessing and Displaying CHM Files: Reasons and Solutions
- How to Create Help Files for .NET (C#) Application in Dr.Explain