The Interface is Technical Communication

By | 2014/09/22

During my recent Webinar with MadCap (recording here), I said something in response to a question that the twitterverse took to:

After Karen tweeted it, it bounced around for quite a while. Perhaps there is a little more to say about this.

Let us start with the basics: the function of an interface is to communicate to the user about how to use the tool. This is true of all interfaces, not just graphical user interfaces. Consider this slide from How to Design a Good API and Why it Matters by Google Principal Software Engineer, Joshua Bloch

Names Matter–API is a Little Language

• Names Should Be Largely Self-Explanatory
_ Avoid cryptic abbreviations
• Be consistent–same word means same thing
_ Throughout API, (Across APIs on the platform)
• Be regular–strive for symmetry
• Code should read like prose
if (car.speed() > 2 * SPEED_LIMIT)
generateAlert(“Watch out for cops!”);

An API, therefore, is a form of technical communication. And this is not an incidental characteristic of an API. It is an essential characteristic, central to its mission and purpose.

The same is true of graphical user interfaces. Check out these 10 User Interface Design Fundamentals from the treehouse blog:

1. Know your user
2. Pay attention to patterns
3. Stay consistent
4. Use visual hierarchy
5. Provide feedback
7. Empower your user
8. Speak their language
9. Keep it simple
10. Keep moving forward

It would be very easy to write an essay, or even a book, on technical communication, using exactly those headings. Interfaces are technical communication.

Where did I get these quotes? I Googled for “How to design a good API” and “How to design a good GUI” respectively. The API quote was result number 1. The GUI quote was result number 5. I did not have to dig far to find quotes that support my case here. They were right on the top of the pile. Making sure that interfaces communicate clearly is top of mind for good interface designers of all kinds. Interfaces are technical communication.

But if interfaces are technical communication, why do we document them? Why create technical communication to describe technical communication?

Part of the reason is that we are often asked to. If your product manager is not thinking deeply about what their documentation needs really are, it is just the sort of thing that will satisfy the documentation item on the checklist. It is easy to do, easy to understand, and relatively inexpensive to produce.

But if product managers are the ones asking for these things, they also tend to be the ones saying “no one reads the documentation anyway”. Is this surprising? If the documentation is only repeating what the interface is already saying, why would anyone read it? It isn’t going to answer any question that the interface does not already answer.

Interface designers, of course, think it is their job to put tech writers out of business. An ideal product, they believe, should not need any documentation at all. The interface should be all the technical communication it needs. This is, in some ways, how they measure their success. As long as interfaces need docs, designers feel they have failed.

But if interfaces are technical communication, what exactly is tech comm for? Does it still have a role? And if it does, how important is that role?

The answers are “yes” and “very” respectively.

What is left for tech comm to do?

Interfaces are tech comm. But the interface is just a face. It is not the whole of the product. It is, of course the part of the product that the user touches and sees. But touching the product is not the whole of their task.

Every product expresses a certain approach to solving a certain class of problem. It is, if you like, the encapsulation and instantiation of a methodology. When someone designs a tool, they are saying, here is the best way to solve this kind of problem — and here is a product you can buy that will make it easier to do it this way.

No where is this more clear than in the tools we use ourselves. The business problem is how to write, manage, and publish content. One school of thought on how to do this is desktop publishing. Its approach it to give the writer a WYSIWYG view of the published document on screen and allow them to manipulate that image to achieve the desired effect.

Before desktop publishing, writers just produced typescripts. It was up to the book designer and the layout artist to determine what it would look like in print. Desktop publishing gave the writer a whole new job to do. Not only must they write, they must lay out a publication. This may seem second nature to us today, but it was a very big step for writers when desktop publishing was new. It came with a whole new vocabulary to learn: fonts, and picas, and points, and pixels, and leading, and kerning, and whitespace.

The interfaces of good desktop publishing programs can communicate how to set leading or select a font. They can’t tell someone who is used to working longhand how to approach the task of creating a document in a desktop publishing application. If you don’t know the craft of document design and layout, the task and the tools will be baffling to you, and the interface is not likely to be much help.

Another approach to the task of creating, managing, and publishing content is  structured writing. Structured writing does away with the visual representation of output, deliberately separating the creation of content from its formatting. The writer if free (and required) to forget everything they ever knew about fonts, kerning, leading, and all that. But they now need to understand a whole new set of concepts: markup, elements, attributes, semantics, and metadata. A structured writing application may have a highly intuitive way of adding attributes to an element, but if you don’t know what attributes are or why you might want them, you are not going to learn it from the interface.

If you have ever opened up an application in a new field, or one that took a radically different approach to a familiar field, you have probably sat and stared at it in mute incomprehension. (I hope it is not just me who does this.) It might be a great UI if you understood the task, and the methodology that the tool implements and supports, but if you don’t, the UI alone is never going to get you across that gap.

The task of the UI is to communicate how to work the machine to someone who knows what the machine is for. This is technical communication, but it is only part of the technical communication that is needed for many products. It can’t help someone who has no idea what the machine is for or the methodology it is designed to support. Even small differences between the methodology built into the machine and the methodology the user is used to can prove to be a huge barrier to understanding.

The biggest limitation of the interface as technical communication is that it can only communicate when the user is looking at it. If the user does not know what part of the interface to look at to achieve their business goals, then the interface cannot possibly communicate that to them, since they are not looking at it. Everything that it takes to get the user to the point where they are looking at the right part of the interface is necessarily the role of documentation.

Unfortunately, this very necessary role is sometimes neglected. If the documentation is simply repeating what the interface is saying, then nothing is doing the vital job of getting the user to the right part of the interface. Documenting an interface can produce an impressive-looking piece of documentation, full of beautiful screenshots and detailed procedures. It can be highly accurate, immaculately written, and well produced. And it will be easy to imagine that with a handsome documentation set like this, new users will have no trouble learning to use the product.

Unfortunately, it is the new user, who is most likely to have trouble figuring out the underlying methodology that the tool is built on, who will be most confused by differences from the methodology they are used to, and who will have the hardest time figuring out which part of the interface they should be looking at.

The way to really help that new user would be to get them to the right part of the interface, with the correct understanding of the methodology, and then leave it up to the interface to communicate how to manipulate the machine.

Let’s do our job and let the interface designers do theirs. After all, we are both technical communicators.

2 thoughts on “The Interface is Technical Communication

  1. Peter Fournier

    This sentence is, in my experience, incorrect:

    "If you have ever opened up an application in a new field, or one that took
    a radically different approach to a familiar field, you have probably sat and
    stared at it in mute incomprehension. "

    The incomprehension is most definitely not mute. I still swear at the Microsoft ribbon daily and the swearing is often quite audible.


    Great article!

    1. Mark Baker

      Well, now you mention it, I guess not all my incomprehension has been mute either. 🙂


Leave a Reply