Docs by Design

I was looking through some classic (i.e., old) examples of technical writing and noticed how the format of application programming interface (API) reference topics hasn’t really changed since these examples were published in 1988 and 1992.

Is this because there’s been no innovation in technical writing during the intervening 30-ish years or, perhaps, we’ve found something that works, so why change? Taking that a step further, if what worked 30 years ago still works, is there any more room for innovation in tech writing?

Here are a couple of examples that I found in my library of software documentation. (It’s a library of printed documentation so there’s not much in there from the 21^st century.)

MS-DOS Encyclopedia (1988)

The first example of classic documentation is from the Microsoft MS-DOS Encyclopedia (Ray Duncan, Microsoft Press, 1988), a 1,570-page collection of everything you’d need to know about programming for MS-DOS (v3.2) in 1988.

It starts with how MS-DOS was originally developed, continues with conceptual overviews of the different operating system functions, how to create common applications and extensions to the operating system, and various reference topics, such as the interrupt example I included here. It’s a one-stop reference manual that would prepare any MS-DOS programmer or device-driver developer for successful coding experiences.

This 33-year-old encyclopedia presents information in a format that you can still see used today.

• Overview
• Conceptual content
• How-to articles of common tasks
• Reference topics on various aspects of the product
• Cross references as make sense

The content in the example reference pages that I included also follows a format that is still seen today:

In most technical writer interviews I’ve had for an organization with public-facing docs, I’ve been asked, “Did you get a chance to read our docs,” which they invariably follow with, “So, what did you think of them?” How should you answer? Here’s what I’ve learned, the hard way.

The answer to the first one, should be a confident (and honest), “Yes!” For, hopefully, obvious reasons. When I’ve interviewed candidates, I have to admit that I wonder why anyone would answer no (and some have). I don’t expect a detailed content inventory but opening a web site and flipping through a couple of pages seem like the least a candidate who is interested in writing them could do—if for no other reason than to see what they’d be getting themselves into.

As to the second one, that has always felt like a bit of trap. For good reason! Here are some possibilities and the traps that lie within.

Their docs are great!

They might be. If so, that’s a good place to start and you should keep going. Saying, “they’re great!” and then smiling politely tells me you either didn’t look at them and don’t want to sound rude or you did but weren’t looking at them with a very critical eye.

What can you say if they really are impressive? Talk about what makes them great and be specific. Some things to talk about include (in no particular order):

• The visual design: Is it attractive? Is it functional? Does it help you find the information on the page?
• The content on the pages: Is it easy to read? Is there sufficient white space? Does it have illustrations? Does it have code samples? Can you understand it? …even if you’re not familiar with the topic?
• The organization and navigation: Are they clear and helpful?
• The performance: Is the site responsive?

These are some generic qualities that apply to almost any type of documentation. To get more specific, you’ll need to find out more about their audience and documentation goals.

Don’t assume you know what they’re trying to accomplish with their docs! (This is the mistake I used to make. Every time.)

Rather, this is where you turn the conversation back to them and have them describe things like their:

• product goals
• documentation goals
• audience
• product
• competition
• work/task scheduling

These are important aspects of the context in which the documents are produced and used, so you’ll want to know about them before continuing your critique.

The way to impress your interviewer with what you know is by the questions you ask as much, if not more than, the answers you give.

Some time ago, I was a filmmaker. Honestly, I wasn’t especially good at it. I wasn’t bad, just OK. However, while I enjoyed the work, using my checkbook balance as a metric, I wasn’t good enough at it to make a living. Because of that, I’m a technical writer.

Filmmaking, however, taught me a lot about technical writing, so I thought I’d share a few of the lessons I learned.

A high-quality film is not the same as a good film

I’m sure you can recall a film that was awful. It could have had excellent lighting, exposure, audio, soundtrack, etc. but you still wonder how you’ll ever get back those 90 minutes of your life. There are many excellent technicians in the film industry who produce technically high-quality material. And yet, somehow all that high-quality material results in a film that is painful to watch endure.

What I learned was that ALL the elements of a film must work towards the goal of telling the story or the film doesn’t work. It’s surprisingly binary. Just being good in a few categories is rarely enough to carry a film.

Except for the story, being good in one aspect rarely makes up for being bad in another. I was a filmmaker before YouTube and home-made videos–around the time reality shows started becoming popular. The importance of story over technical quality (caveat: the audio must always be acceptable) was clear. Since then, what you see trending on YouTube should convince you that story is still king.

With technical docs, I see a lot of concern over “technical” quality, such as spelling, language, vocabulary, and bugs fixed. I’m not saying these elements aren’t important. But, if you’re not telling your audience what they want to know, how well it’s spelled isn’t going to matter. I was surprised to see a similar discount of technical quality in my dissertation study (see API reference topic study – summary results). The problem, unfortunately, is that it’s easier to count these technical qualities, so it’s deceptively attractive to equate technical quality with document quality or utility. Technical quality might be a factor in utility, but it’s not a proxy.

Don’t give the audience a reason to leave

A film must tell a story in a way that keeps the audience wanting to know what’s next. Whether the film is a 10-second commercial or a 90-minute feature, crafting a story in such a way is a skill that takes practice and a knowledge of your audience. It’s an aspect of the film that starts with the script and must be supported all the way through production, editing, and release. It’s one of those things that, if not done well, can result in one of the bad examples I referred to in the previous lesson.