A review of the Noughty’s – Part 1
David Farbey tweeted recently on how he had noticed how everyone had started summarising the years 2000 to 2009. As the end of a decade is such a momentous event (?) it is probably inevitable that editors struggling for a story during what is called “the silly season” turn to an easy fix. Not to be outdone, and honoring the fact that I have, officially at least, been a Technical Writer since 1999, I offer my own completely unscientific review of how the technical communication world has changed in the last ten years.
Note: I have split the review up into parts. Part One covers the migration from static offline help to user generated on line help.
Help….WinHelp!
In the good ol’ days when I had loads of money (pre-marriage) a full head of hair (also pre-marriage and pre-work) and technical communicators were easily pleased, I produced my first piece of documentation in WinHelp format. The sleek, familiar user interface made my first foray in technical writing a relative breeze. Oh how the mighty has fallen. One look at a WinHelp project these days makes me wince. OK there were some good things about it (e.g. non-scrolling regions) but on the whole it just doesn’t cut it in today’s feature rich, customer interaction environment. They just didn’t provide enough functionality for the discerning user and we Technical Writers just had to go. Whilst they are still used to this day, despite Microsoft’s best efforts, they are few and far between having largely been relegated to legacy help files for old and tired applications that have yet to be sunset or assigned a budget to upgrade.
The step to Microsoft HTML Help brought with it a rich stream of possibilities to improve user content. Like anything new it required a certain amount of getting used to, not least the fact that it was coded using HTML, but on the whole it was a huge step forward. Just the fact that you weren’t using MS Word as your editor was surely reason enough to change. However rather ironically a number of Help Authoring Tools surfaced that allowed you to generate the required HTML from a MS Word like interface. Now you could produce HTML in from a familiar interface without the vagaries of the familiar application! All of a sudden you could produce your HTML code without ever coding anything. Whilst it is possible to create your HTML topics in Notepad (I know someone who does even now) tools like Adobe RoboHelp provided an MS Word like user interface with which to produce your works of art. Microsoft HTML Help also brought with it a range of new gadgets and tools that allowed you to enrich your content (e.g. DHTML, browse sequences, forms, etc.).
However arguably even Microsoft HTML Help has its day. Whilst CHM files are still widely used and probably will be for sometime to come, the arrival of the Internet brought with it the need for online content. With the concept of a CHM being that they are designed to run on a local PC, we often used to see if we could bend the rules by placing them online. This worked to a degree but the incessant need for 100% security soon drove a dagger into any CHM file located online. They were deemed to be a risk and after Microsoft released Security Update 896358 in June 2005 they could no longer be effective unless located on a local drive.
Online help became the buzzword of the day. Outputs like WebHelp and FlashHelp gave Technical Writers the ability to change from being purely content providers to someone who could start to change the look and feel of the documentation we provided. The advent of skins allowed us to design the interface to the documentation as well as the documentation itself. What is more these outputs were more flexible allowing us to place them on internal intranets or an external site. Now our users could access the very latest documentation without having to install or upgrade an application. What is more, they could do so from anywhere provided they had an internet connection. All of a sudden staff in the field became enabled to find information quickly and easily.
Now I can’t let a review of output formats of the last ten years go by without mentioning my nemesis. For a short period after taking on my current position I was tasked with producing JavaHelp. The misguided decision made before I joined that this was the required output type because our application was written in Java was soon reversed! As soon as I pointed out the long list of its limitations and more importantly the negative feedback we were getting from users, particularly around searching, we managed to get agreement to change. If anything, it was this decision that highlights the changes that have occurred throughout my career. Namely that the documentation function has gone from something that costs, to something that can add real value to the product. The powers to be can see that it eases pressure points and can be a real difference to the overall user experience.
Deleting Legacy WebHelp / WebHelp Pro Output Files
My wife and I have a running joke about how we organize things. I like order. It’s a man thing I guess. CDs are in racks sorted alphabetically by artist and books are sorted by genre and then size. It’s neat, tidy and easy to manage. Her method of organising is to have lots of piles of stuff littered everywhere. What is even worse is that she knows exactly in which pile that receipt for £2.49 for a cheap brooch bought nine months ago is! I digress!
When it comes to RoboHelp WebHelp and WebHelp Pro output files I am equally as anal. Things are a little easier of course as the files are very handily located in a folder all of their own and are generated / published to a location of your own choosing. But over time you can end up with lots of erroneous files. Take for example a project that is generated and published for the first time. Everything is brand spanking new and the output files are exactly what you require. Move on a few project versions and you may have renamed topic files, deleted baggage files, amalgamated map files, deleted index and/or TOC files. In fact just about any change to a project can result in a previously generated / published output file to be redundant. To make matters worse, because of the publishing workflow you have a duplicate of everything. Your generation directory has the output as it was created by your Single Source Layout. Your published location has a copy of it. So to delete files you have to go to both locations via Windows Explorer and manually delete them.
Of course if you are not bothered by redundant files it really doesn’t matter. They don’t do any harm apart from clogging up disk space, but me being me I like to keep things clean. The problem is, there is no way to clean up redundant files from within RoboHelp. This is a bit of an oversight in my opinion and some single source layout option to delete them would be useful. Maybe I’ll go and submit another feature request before filling a copy away in my Microsoft OneNote notebook; filed alphabetically of course 
Output files and so(u)rcery
The difference between a RoboHelp project’s source and output files can be an area of much confusion. This is especially true where users are more used to WinHelp, compiled HTML (CHM) or compressed JavaHelp output. With these output types you have one or two output files to worry about. Web based output however, has many more. Whilst it may seem unnecessary to understand the difference between the output and source files, it is essential in certain instances.
Take the scenario where you are faced with making changes to a legacy project that you have no knowledge of. You have the output but you don’t have the source. It is a common misconception that to recreate a project you just need to import the output files and, hey presto, off you go. Nothing could be further from the truth. In such instances it is always best to explore all avenues to find the source files. Or how about the scenario where you have a WebHelp project that is published to a test area, but which needs to be copied to a company intranet of SharePoint site once testing is complete. You could just republish to another location or manually copy the files, but which files should be copied?
Web based output types (WebHelp, WebHelp Pro, FlashHelp or FlashHelp Pro) output a series of files in a folder structure that largely mirrors the project’s folder structure. However there are some anomalies. For a start you may notice some additional folders. These contain versions of the output uses in different circumstances. The “whdata” folder contains DHTML files used by some older browsers. The “whxdata” folder contains output used in Java applet and DHTML versions on newer browsers. The “whgdata” folder contains pure HTML.
There are also other files likely to unfamiliar to those who haven’t seen them before. These include files related to context sensitive help, framesets, skins, style sheets and all manner of JavaScript files required by various elements of the help. These files are too numerous to list here but are well documented in the RoboHelp help file.
Users with access to web based output files often find there is no .XPJ file with which to open the project. This is a sign that you haven’t got the source. Some even try creating a new project and import the .HTM files they find in the output. If you do this, you are asking for trouble as the .HTM output produced by RoboHelp contains additional code which when imported back into a project causes it to complain loudly. Try creating a new project and importing a few WebHelp output files to see what I mean.
Compiled HTML output, as the description implies, compiles a set of HTML source files into a single deliverable file (.CHM). The file contains all that is required to display and use the file content and as such is, to this day, a natural choice for applications being installed locally on a client PC. Creating a new help file from a CHM however is relatively straightforward. RoboHelp has its own tool called HTML Help Studio that decompiles a CHM file into its constituent parts allowing you to create a new project from them. Just create a directory, select a CHM and point it at the directory and before you know it you have everything you need to proceed.
Before Compiled HTML output there was WinHelp. This uses Microsoft Word as the editor to produce a series of .RTF files from which a .HLP and a .CNT file are generated. The .HLP file is the package for the help and contains the tri-pane view and the topic area. The .CNT file contains the Table of Contents data and must be shipped with the .HLP file and installed in the same directory for the Table of Contents to be displayed. This output type is no longer widely used and cannot be used on Windows Vista or Windows Server 2008 PCs without downloading and installing the WinHlp32.exe, as it is not part of these Windows installs.
JavaHelp comes in two formats; uncompressed and compressed. Uncompressed JavaHelp produced a series of files in a folder structure in a similar fashion to WebHelp or FlashHelp output. Compressed JavaHelp outputs a single .JAR file. This is a bit like a compressed WinZip file and can be displayed in a JavaHelp viewer. As it is a single file, it is the favored method of delivery.
