Technical Writing, Documentation, and Training

404-873-4288

Our Blog

Expert tips, advice, opinions, and viewpoints.

Objectivity tends to be one of the core values of technical fields. The fundamental laws of physics dictate the properties of microprocessors, and chemistry defines the properties of the materials we use. These methods make up the API, determining how that application behaves and what it is capable of doing. The way that people interact with technology, however, is anything but objective. They bring a lifetime’s worth of experiences that guide their behavior and frame their expectations for both what the technology will do for them and how it will perform its duty.

Good design can only go so far towards bridging the gap between people’s expectations and the basic components and interactions that comprise any piece of technology. Differentiating alerts and confirmations using color, interface elements that behave like physical objects and that users can interact with directly, and integrated skeuomorphs – these can all provide important queues about how to interact with technology and show us its purpose. They can’t tell the whole story, though. Design decisions often rely on contextual queues which may not make sense when the technology is taken out of the lab or office.

In these cases, good documentation can help manage people’s expectations by making a direct connection between how a tool or program works and how people engage with it. It can also be an opportunity to frame user engagement in a social or cultural setting, helping them to make connections between why a designer made the decisions he did and how those decisions apply in different contexts.

For example, I recently worked on a museum exhibition that collected maps of central Africa from the 17th century to the 1960s. Maps are extremely sophisticated technical documents. They illustrate scientifically objective information – the precise location of some real or imaginary site, e.g. natural resources or political boundaries – but how they represent that information is deeply embedded in cultural contexts and history. Because they exist on this boundary between objective and subjective, they often contain context queues about their intended purposes or the cultures that created them. A map with a cover page advertising a local gasoline chain prioritizes roads, and by doing so reveals something about the culture that produced that map; it values transportation networks. In this case, the roads are even more important than the points they connect.

Another map in the collection has illustrations outlining its border that shows the different tribes who inhabit the regions shown on the map. This map may have aided the development of diplomatic relationships between early European missionaries and the peoples of the Congo region. Illustrations of different types of people indicate that they were in fact seen as people by the creators of this map as opposed to being seen simply as a resource, which is often how later maps treated the people of central Africa.

Thinking about how these maps imply not just their intentions, but their place within a culture and how that culture values the ideas that they represent can lead to new opportunities for other technical documents. Dry, boring, ugly documentation implies that the product it describes has the same qualities. Quick-start guides value simplicity at the expense of showing how powerful a product might be. Eschewing documentation altogether claims that a product is easy to use, but it can lead to users feeling stupid or inadequate when they can’t figure out how to use it properly. Even deeply technical documents, like programming guides and API documentation, can frame the products in different ways, by emphasizing particular sets of methods or encouraging best practices.

When thinking about how to document a product, it’s important to consider more than just the facts that will be presented. The format, the visual design, and the branding all affect people’s relationship to the documents and can ultimately affect a person’s relationship with the product. Documentation can be a way to engage users and frame their experiences, but only if as much attention is paid to the design of the documentation as to the design of the product.

View More Posts by: Paul

Leave a Reply