Problems with the Existing Documentation Tools

The Existing Toolchain
Connecting up to Word Doctor Output
Other Problems
Resistance to Change

The Existing Toolchain

The existing toolchain was, as already mentioned, based on a Microsoft Word master document. Producing hard copy was as simple as CTRL+P, followed by a dialog about printer settings and some manual labour involving a ring binder. It's fair to say that the printed output looked pretty much exactly as previewed: the author had good control over pagination, positioning of images, fonts, colours and so on.

The linked online pages took more effort. We'd got a license for a tool which I'll call Word Doctor (not its real name—I'm using an alias because I'm going to moan about it). Generating the linked web pages using Word Doctor involved the following steps:

  1. Create a new Project.
  2. Point it at the Microsoft Word Master.
  3. Select some project options from the Word Doctor GUI.
  4. Click the build button (experts, hit F5).
  5. Make a cup of tea while the pages generate.

All fairly easy—in theory. In practice, there were some other steps which the Word Doctor user manual neglected to mention:

  1. Exit Microsoft Word. Word Doctor has trouble accessing the document otherwise.
  2. Restart your PC. For some reason a resource got terminally locked up.
  3. Rewrite the Microsoft Word master using the Word Doctor document template.
  4. Don't forget to exit Microsoft Word!
  5. Create a new project etc.
  6. Click the build button.
  7. Click away a few warnings about saving TEMPLATE.DOT and OLE something or other.
  8. Read the Word Doctor workarounds Wiki page on the intranet.
  9. Click the build button again.
  10. Go for lunch. Documentation builds took around half an hour.

I am not exaggerating. The engineering manager admitted that he estimated it took at least two days of struggling to convert a Microsoft Word master into the online form. And nor do I blame Word Doctor. I don't think Microsoft Word comes with a decent developer API. Instead, it tries to do everything itself: from revision control, through styling, to HTML output. It uses an opaque binary file format to deter anyone from trying to develop tools to work with it.

The final irritation was with the Word Doctor output—if you ever got any. The HTML was packed with Internet Explorer specific Javascript, and looked poor in any other browser.

Connecting up to Word Doctor Output

The real downside of Word Doctor was when it came to trying to connect the Product to the Word Doctor web pages. This job fell to me. It was a multi-layered integration task:

  • on a team level I would work with the technical author to ensure the documentation content was correct, and contained the required Help topics.
  • on the Product side, the web-based user interface would call for help using a text identifier. The Help subsystem would use the identifier to look up an HTML location—a page and an anchor within that page—and it could then pop up a new window viewing this location.
  • on the documentation side, I would have to configure Word Doctor to ensure its HTML output included the right locations.

Unfortunately, there were problems with each of these layers.

Personally, I got on well with the technical author, but the documentation tools made it extremely hard for us to work on the same file. We had to take it in turns or work with copies. I couldn't even fix a typo directly.

The Word Doctor output was a frame-based collection of static HTML pages. Now, externally referencing a particular location in such a set of pages is tricky—due to the limitations of frames—so the Product's help sub-system had to dynamically generate a framed front page displaying the appropriate left and right pane each time it was called. Not too difficult, but more complex than strictly necessary.

Both pages and anchors were a moving target in the Word Doctor output. Every time you added a new section to the document you broke most of the help references. Thus we found ourselves in a situation where the technical author wanted the Product to stabilise in order to document it and I needed the documentation to stabilise in order to link to it.

Other Problems

Microsoft Word uses a proprietary binary format. This ties you into their product to a degree—effectively, you're relying on Microsoft to look after your data because you simply cannot work with this data without their tool. Of course, the risk of Microsoft collapsing during the lifetime of your document may be one you can live with, but you are also vulnerable to them ceasing to support the version of Word you prefer, or charging an unreasonable amoount for an upgrade. It also means:

  • it's extremely hard for more than one person to work on a document at a time since changes to binary files cannot be merged together easily.
  • revision control becomes more expensive and less useful (how do you view the differences between two versions of the manual?)
  • it is very difficult to automate anything. As a trivial example, Word Doctor had no batch interface—it required human input at every stage. Now consider trying to rebadge the manual, perhaps for redistribution of the Product by some partner company. With a decent documentation toolchain this should be as simple as the build prepare target copying the correct logo graphic into place and applying a simple transformation to some text strings.

Resistance to Change

Despite all of these limitations and irritations it was hard to convince anyone a change was necessary or even desirable. The reasons were as much organisational as technical.

  • The existing tools had been used to produce acceptable end user documentation in the past for other products shipped by the company.
  • Already, considerable effort had been put into the Word master for the new Product (even if much of it would have to be scrapped due to the inevitable changes as the Product developed).
  • The engineering team had more work than it could cope with already. At least the user documentation could be outsourced to a contract technical author.
  • Setting up a smarter toolchain would need engineering input, and, once the tools were in place, would the technical author be able to use them productively?
  • The sales team saw the documentation task as non-urgent for much the same reason that they saw user input validation as a nice-to-have rather than a priority. After all, they'd run some promising beta trials at customer sites using a poorly documented and inputs-unchecked version of the Product. They were happy to continue to provide support and tuition as required, either on site, by phone or by email.

I could (and did) argue against all of these points:

  • Existing documentation was stand-alone: it did not have to integrate with what it documented.
  • Using the existing tools to connect the new Product with its documentation looked like being a continual sink of effort.
  • The engineering team probably spent as long telling the technical author what to write as they might have spent writing it themselves.
  • Surely the technical author would quickly master a new documentation tool?
  • In fact it was more often the engineers than the sales team who provided support, and frequently for problems which could have been avoided with better input checking and more solid documentation.

As software engineers we need to concentrate on the software. That means listening to the sales team; but when it comes to software quality, we know best. I believe the only shortcut is to prune back the feature list and, increasingly, I regard it as wrong to view software documentation as an add-on. Decent documentation is one of the first things I look for when I evaluate a piece of software: the website, the user interface, the README, the FAQ list, and of course the source code itself (if available). Quite simply, I didn't want to deliver a Product with poor documentation. I didn't think it would save us time in the short or long term.

Copyright © 2006 Thomas Guest