What good documentation looks like

A few years back, I was working as a tech writer for a company which made medical software. We were trying to get an important certification that we’d need to sell our product. And a crucial part of that was good documentation: we had to show how it worked, what it did, how it tracked everything, how it was secure, etc. Well, that’s what you have a tech writer for, so all is good.

It’s important to know, I didn’t have any existing documentation to work with. There was a wiki which had the developers’ notes in it, but that’s it. Nothing by way of formal hand-it-to-an-outside-entity documentation.

Okay, that’s not too abnormal; tech writing is expensive, and many companies don’t bother with it until an auditor is breathing down their neck. Hardly ideal, but to be expected, and I did have time. So, I set to it.

Since there wasn’t any existing documentation to re-do, I based my organization around the expectations set by the certification. And, a good week before the deadline, I turned in the completed documentation, all 100-something pages of it.

And that’s when disaster struck. The auditors decided they wanted the documentation in a completely different format – they weren’t going to read our documentation, no. They wanted us to fill out a questionnaire. The questionnaire was very comprehensive, encompassing exactly as much material as my documentation covered. And I had less than a week to complete it. I told my boss “No problem.” And I gave him the completed questionnaire in 3 days.

How? How could I turn an entire manual into a completed questionnaire in 3 days? If you’re thinking “An awful lot of copy and paste” you’re on the right track, but you haven’t fired up the engine yet.

Before I started the project, I had sought and gained permission to try something different. I decided to try Topic-Based Authoring. With topic-based authoring, rather than create complete documents I create small topic “nuggets” (I prefer to think of them as Lego bricks, but the technical term is modules) which consist of one or two standalone paragraphs on a single topic. I acquired some inexpensive software that integrated between Word and SharePoint, and after loading my nuggets into SharePoint I could assemble them in any form I desired, leaving me basically to write the introduction and conclusion to a given document and select what information should be included. Since I had determined what nuggets I would write based on the certification requirements, I knew I already had all the information they needed. So all I had to do was insert them into the questionnaire, check to make sure the formatting was correct and that each question was fully answered – or if not, edit the nugget in the database NOT in the document itself – and sing the praises of topic-based authoring.

Needless to say, I love topic-based authoring. It’s not just about being able to restructure documents quickly. It’s also about being able to rapidly change information. While I was working on the documentation, development was still ongoing. I was able to change single nuggets of information to reflect changes in the system, rather than going in and changing each document. And because I wasn’t sitting and staring at a given document for days or weeks, it reduced burnout. As an added bonus, I was even able to get some of the subject matter experts (SMEs, e.g. developers and system administrators) to write up about specific components, saving time and effort.

Topic-based authoring can be hard to implement. It’s not for everyone: the software can be expensive, the cost of changing documentation methods can be immense, and reusability may be very low. But whatever your documentation method is, you should think about being able to do what I did. Your documentation should always offer the following:

It should be accurate. I can’t say how many times I’ve found outdated documentation that simply doesn’t reflect current systems or processes. As an auditor, that tells me the documentation isn’t maintained, and that means I can’t trust any of it. That means my work will take longer, and ultimately that will cost you money.

It should be flexible. You never know when you’ll need to change formats, add data, or meet some other unexpected demand. A company’s ability to meet new demands is one of its most important skills.

It should be fast. “I’ll get back to you in a month” hasn’t been an acceptable answer since the 80s. No matter what it is, you’re going to have to generate new documentation at a pace that would have been considered simply impossible, regardless of resources, before modern computing.

It should be consistent. All of your documentation should reflect the same information. Anything less will reduce confidence and engender confusion. And that’s never a good thing, no matter who reads it.

Good documentation practices are life and death to any company. It’s always tempting to wait until you need documentation before hiring a tech writer. Let me resolve that quandary: you need good documentation Right Now. Because if you wait until you realize you need it, it could well be too late.