Much recent time has gone to writing design documents (fun). As usual, this is sucking up more time than I would like, in part because I find the available tools so poorly suited.

Lets set some requirements. (Oh goody, more requirements to write down…)

  • Documents should be readable by anyone on the distribution list - i.e. no specialized reader software. Anyone has a web browser, Adobe Reader, and a MS Word (or in my case - OpenOffice) installed.
  • Document templates should be in form a usable by all development folk within the company. That pretty much rules out TeX or the like, and any software with a stiff per-seat price.
  • It would be nice if the documents could be displayed from the web.

Used Google’s on-line document editor to write a “rationale” document - essentially somewhat free-form story describing what have done, what we are doing, and what we are going to do. For this purpose docs.google.com is pretty nice. Export to MS Word *.doc format is decent. Export to HTML is … the visual result is pretty good, but the generated HTML is a little messy. Good enough for this task.

For the documents with a bit more structure, there isn’t anything very satisfactory. Given the somewhat well defined structure, seems we would be best off with some sort of structured document format. XML seems like a logical choice, in that we could capture the logical structure of the document. Editing and presentation are problems. Presentation less so, as a transform to HTML is probably no more than tedious. Editing is not so easy. How do you edit an XML document from a template without distracting the writer? Mundane tasks - like embedding an image - are trouble (you don’t really want the image in a separate file).

We have MS Word documents as templates for the structured documents. I find it incredibly annoying, every time I have to work with one of the templates, as these are not good examples even of MS Word documents. I could generate cleaned-up documents to replace the existing templates, but … I do not want to expend the energy needed to got updated templates adopted by the company when I really want something better.

I suspect that OpenOffice could be adopted as a base for a structured document editor. The model of bundled XML and associated files in a ZIP seems an inherently extensible base. If I had a few months of free time (which I do not), perhaps OpenOffice could adapted to the purpose.

Oddly enough, I find myself missing Interleaf. Many years ago FileNet had a (somewhat unreliable) port of Interleaf on their machines (we are talking about mid/late 1980’s). Ignoring it’s many failings, Interleaf had one strength - in that you were more aware of and had more control over the styles used in the document. As I remember (and this was long ago), the named style for each composite document element was shown in a gutter on the left(?) side of the screen. Changes to document format could be affected by editing the stylesheet associated with the named style.

MS Word has something similar in that there is an option (unknown to most MS Word users) to display associated styles in a gutter. MS Word is somewhat clumsy in this sort of use, as accidental or ad hoc local modifications to a common style are hard to detect. Changing the format of a common element is often only partly successful, in that you have to visually scan the entire document for elements that did not format as intended, then do a bunch of tedious poking around through dialogs trying to find the problem. The pursuit of easy WYSIWYG has made MS Word difficult to use if you want to maintain a consistent document format and structure.

Unfortunately OpenOffice - the GUI in particular - is slightly worse in this regard. The “Styles and Formatting” panel is far inferior to displayed named styles outside the page margin. Worse, for some reason(?) the named style shown in the panel is only sometimes the style of the current document element (no idea why this is). Also, as with MS Word, there is no easy way to detect a locally modified style.

What I’d really like to do is take a year off, and write a web-based structured document editor, but … oh well.