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:
All fairly easy—in theory. In practice, there were some other steps which the Word Doctor user manual neglected to mention:
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 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:
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.
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:
preparetarget copying the correct logo graphic into place and applying a simple transformation to some text strings.
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.
I could (and did) argue against all of these points:
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|