6MarChoosing a documentation format

There are a multitude of tools available today for creating documentation. And with all of these choices comes a multitude of file formats. Many clients we come across insist on a specific format (usually for legacy reasons), but would benefit greatly from another format if they considered some of the usability and authoring issues associated with each. In this article we’ll summarize the pros and cons of 4 common document formats, so that you can make the best choice for your next project.

-PDFs (portable document format) – PDF files are read only documents which you can think of as hard copies viewable on-screen (there are also interactive PDFs but that’s another story).

Pros: PDFs are great for printing because they are device independent and should (in theory) look correct on all devices and printers. PDFs can also be generated by a wide variety programs including Word (via a special plug-in) and the file size often compresses well.

Cons: PDFs can be difficult to search, especially when documentation is split over a library of separate PDF files. This makes it difficult for the user to know which file to look in for a specific topic and the only workaround is to do a “find in files” operation. Also, like most non-web based formats, once a PDF is out in the public, there is no version control, so a user can easily mismatch the document and product versions by accident. For more info on PDF’s see: Intro to PDF file specifications and 18 introductory facts about PDF files.

-chm/Winhelp –chm (MS compiled help) and Winhelp formats both package up all of the help content and provide additional tools like a table of contents (TOC), indexing and searching. Chm is the successor to WinHelp.

Pros: everything is bundled up in one package and is very lightweight. Chm files are standalone and can be executed on their own, although WinHelp files require Microsoft’s free Winhelp tool to display. The TOC, index and search features provide powerful tools for the user to find content easily.

Cons: both formats are showing their age and are being phased out in favour of new formats like webhelp. Both formats are Windows specific and require special authoring tools. For Winhelp, you will often have to install Microsoft’s free help compiler in addition to the authoring tool. Navigation with Winhelp is also difficult as the user cannot easily display the TOC and the content concurrently.

-Webhelp – Webhelp is our favourite format. You can think of it as an online version of a chm. It includes powerful tools like a TOC, index and searching.

Pros: The biggest advantage is that the author can control the content and ensure that it is up-to-date. Since the content only lives online, you don’t have to worry about old revisions of files floating around “out there”. The content is also device independent html (accessed using a web browser).

Cons: Requires a webserver to host. We’ve also found that if a page of help has videos, a good portion of the video content must be loaded before the page is available, thus slowing down the loading of the page. This format also requires specialized software to create it such as Help and Manual.

-Word/text files – This is content in its most purest form and is pretty self explanatory.
Pros: Everyone has a program which can save out Word or text files, so the costs of authoring tools are probably already covered in your organization. Text files can be very small and lightweight making them perfect for things like release notes or installation instructions. Word files can easily be passed between authors. Also the file itself is the output, so there is no transformation step to generate output as is the case when generating other formats.

Cons: Word files cannot be edited concurrently making them difficult to author in a team environment. We’ve also found a number of discrepancies when editing Word files on the Mac especially when using some of Word’s advanced features (though in generally it works pretty good). There are no controls for locking the content, which could be an issue for important documents like legal files.