dtm | Why I don't like Word for writing documentation (Reply)

This is a technical/work entry. I'll do a Katherine update at some point in the not-too-distant future.

Occasionally, even the most insulated-from-the-customer programmer must write some sort of documentation. (I'm actually not nearly as insulated from the customer as I might pretend to be) Recently, a piece of install documentation that I had been maintaining in reStructuredText was officially transferred to the publications group, and since then it has been a Word document, though I am still expected to submit updates. At one point I noted that I would be much happier maintaining that documentation in the plain text format I had been using before, and was asked by publications “Dan, what do you want to do with the doc in plain text that you can't do if it's in Word format?” — this is my reply to that question, with some slight rewording and elaboration.

The truth is, there probably isn't anything I can't do if it's in word format, but there are things that become more difficult.

First off, it becomes difficult to update the documentation in tandem with changes made to the program, because the switch between Word and the various plain text editors we use for writing code is significant enough that it's much easier to update the code and the documentation in two steps. That is, this documentation format change causes changes in the work style. Maybe this is a good thing; while it certainly encourages me not to let the documentation become out-of-date, it may also encourage limiting changes to those where we have a clear specification.

Secondly, I find that subtle errors occasionally crop up in Word documents that people tend to just ignore because it's too much of a hassle to get the document clean. For example, in the current Word version of the install documentation, there are two numbered lists that should be both numbered 1–5, but instead the second one is numbered 6–10. Related to this is the automatic corrections that Word will make (capitalizing words, for example) when one merely scrolls through a document with the arrow keys. It is especially frustrating to edit one part of a document, scroll down to a later part, and discover after the fact that Word silently adjusted commands that were in the portion you scrolled past. We have also had serious trouble in the past with Word's autocorrection changing a simple dash character ("-") into an en-dash, or inserting "smart quotes" into a command line, which results in a command line that can't be cut-and-pasted into a cmd or terminal window.

Third, Word documents are harder to work with in source control than plain text documents. Not that Word documents can't be stored in source control — they can — but it's difficult to display the changes to a document as made in one release to the next. This is much less of a concern if publications owns this document, but I worry that we may have trouble determining exactly where the authoritative version of the document is for each release of the software.

Finally, one thing that becomes easier with a Word document that I think should be harder is that it becomes easier to just throw the file as-is up on the webserver we're using to distribute the release internally, instead of doing the right thing and converting it to html. Even when using internet explorer, I find that there's a noticeable delay in loading a word document as opposed to an html page. When using firefox, this is much more noticeable. As our software is being deployed on Linux, we should also consider the possibility that the installation document should be easily readable without having Word available. Of course, in some sense this is just a matter of discipline when putting together a release, as Word does have decent export-to-html capabilities.

Note that none of these are really fatal objections to using Word format. The autocorrection issue can be worked around by disabling all autocorrection completely, or by the use of special Word styles for command lines and other things such as filenames that should not be subject to autocorrection. It has been my experience, however, that it is very, very rare for anyone (programmer or non-programmer, Word expert or not) to take advantage even of the styles that already exist in a document handed to them. Also, I recognize that the learning curve of the plain text markup format I use may in fact be significant for non-programmers; especially, the pattern of:
edit the plaintext
run some program to turn plain text to html
see how the html looks in a browser
may strike non-programmers as a bizarre way of working when WYSIWYG or near-WYSIWYG tools such as Word are available. There's also the matter of installing the necessary tools to turn the plain text I was using into html.

In short, if publications is going to own this document, I will not object to it being maintained in Word format. However, for the reasons above, I think that you can still expect that at least the initial versions of documentation generated by programmers will be in plain text form, or in html produced by running that plain text through some formatting tool. (at least for small documents like this one — I admit that Word is probably the appropriate tool for a hundred-page detailed specifications document)

For reference, I then attached the last version of the install document that was in reStructuredText and the html that produced, to give a flavor of the format I was using when I said "plain text". You can get a similar taste of the format from one of the documents on the reStructuredText website.