Technical Writing

Huge Specifications

Earlier in my career I had been responsible for writing Data Sheets and Application Notes. My new position, working on MHL, involved writing and editing the specification and compliance test spec, each of which were several hundred pages long. And they had multiple contributors, and multiple iterations of edits, corrections, clarifications, re-writes, etc.

Microsoft had improved Word since the 1990s, but it still was not an out-of-the-box content management tool. The company had struggled to justify putting in place a real content management tool, and – at best – had installed a document repository. So, what was I to do to manage the changes and reviews and approvals for these massive documents?

The work I was doing in Word was already seen as ‘magic’ by most of my peers. They were terrific engineers, but had never been called on to master Word.


I thought back to work I had done in Visual Basic some years before. I read up on the macro usage and object-oriented structure of Word. And, working in spare time for a couple of weeks, developed some lengthy macros, and a style of tracking changes, that served the team well for over 5 years.

Many times a question would come up: “Who requested this change on page XXX?” With the change history and notes in the document itself, I could answer this each time. When reviewers groaned at having to re-read the next draft, again at hundreds of pages, I explained, “You can just review the changes by using the history at the back of the document.” A sigh of relief, and the project moved forward.

I used the same approach to partially automate checking for field names used throughout the compliance test specification, and to generate various versions of the form to be used by customers with that spec. I searched for, but never really found, the best tool to migrate such form automation from Office documents to XML or even to Wiki pages. This is a challenge for the next project.