Why design intentions are key in technical documentation

To be of value to customers, technical writers need to be able to understand their needs. Equally important is the need to understand the design intentions of the product to guide customers to using the product in the way it is intended. So, how do we meet these needs?

Imagine this: you’re a busy farmer with a field that needs to be plowed. Instead of using a horse or tractor, you wonder if you could use your race car. You decide to call up the race car manufacturer. They provide you with instructions on how to weld a towbar onto your car to attach a plow.

But just the fact that it’s possible doesn’t make it a good idea.

This, of course, is a silly example, but the point is to illustrate something that can happen in businesses that deal with complex and multi-faceted products. However, technical writers can be the first line of defense to identify and handle these cases.

In the example above, the company receiving that request should obviously have answered “You shouldn’t do that. A race car isn’t designed to pull a plow in a field”. In this example, the gap between what the product does and what the customer asks for is apparent. This request is setting both the customer and the product up for failure.

Unfortunately, in other situations, it’s not always that apparent.

So how is this relevant to you as a technical writer?

A lot, if not the majority, of the discourse around what a technical writer brings to the table is about the audience. We know the audience. We tailor our language and our delivery to the audience. We create the link between the product and the users, the audience. And while this is certainly true, this is not the only thing we do.

If we focus solely on the audience, we risk missing the intentions of the design. We risk telling someone how to hitch a plow to a race car. We risk getting too invested in the wants of the audience and not invested enough as advocates of the product.

Let’s start with the utopia: The customer has a specific goal in mind that they want to achieve. The product is the ideal solution for accomplishing that goal. The user guidance describes exactly how to do this in a way that is easily accessible to the customer, because the technical writer is well embedded in both what the product does, and what the customer wants to do.

This may be a less common problem, but I’ve seen it (and been the cause of it) several times. In this situation, the writer is completely embedded in the product. They have deep and extensive technical knowledge, and are a power user of the product itself. However, the writer has not spent the time and effort to listen to and understand what the customer is using it for, or how they ingest technical user guidance in the most effective way.

Perhaps the reason this issue has not been addressed more frequently in the past is because the discussion around the key value addition of a technical writer is focused on the understanding of the customer, our audience.

With this audience-focused approach, we instead risk losing touch with the product. We listen intently to the customer’s request to pull a plow with their race car. We consult our subject matter experts on how to weld a towbar to the car, and we deliver.

At this point it is important to distinguish between product knowledge and understanding of the intention of the design. It is entirely possible to be a deeply knowledgeable product expert without having the slightest idea of design intentions. In fact, this is an obvious risk in modern product development. And this doesn’t just apply to technical writers. This happens to developers, engineers, testers, and many other roles as well.

When a product is originally conceptualized, it has a strong design intention. This is because it originates from a problem that the designer or inventor wants to solve, and the product is the means to solve that problem.

If the product is successful, it is likely there will be more people needed to develop it. More customers will want to use it, some of them in new ways. Somewhere in this expansion, technical writers are brought in to provide user guidance.

If the original design intentions are not strongly communicated in this process, they are lost. What is left is the product, which at this point‌ may have a plethora of configuration options and many use cases it was not originally intended to address.

This brings us back to the much-discussed topic of the value a technical writer brings to the table. The drawings used to illustrate the three cases can be interpreted as knowledge horizons¹, and their overlap can illustrate to what extent these knowledge horizons are shared.

To be of value to the customer, we need to understand their needs. We need to share their knowledge horizon. This is something most people agree on. It adds value and usability to the product itself, making it better. One way to view this is that we shorten the path from the audience to us and vice versa, because the circles overlap. There is less effort needed to cross the divide.

Equally important, however, and frequently overlooked, is the need to understand the design intentions of the product, to guide customers to using the product as it is intended. This adds value to the teams we work with, because they can rely on the fact that we understand what the product is for, and that we ask them relevant questions when needed. We ensure that the circles overlap, minimizing the effort needed to cross the divide. We also help our audience use the product in the intended way, which improves their product experience. A race car is much more enjoyable on the road than in a field.

An expanding product team is caused by someone not having the time to perform a task because it is starting to take up too much time for one person. If the new team member requires extensive effort from the original team to do what is needed (by having to repeatedly explain one’s knowledge horizon), the value of expanding the team is significantly reduced.

In short, if we understand design intentions, we will not be asking the product team how to weld a towbar to a race car.

¹To understand the theory of knowledge horizons, I recommend looking for literature on hermeneutics, especially Hans-Georg Gadamer.

Currently, there is much discussion around how we will work in the future. And, with the advent of things like ChatGPT, one of the most discussed tools in our field is artificial intelligence.

What the future will hold is always difficult to predict, but what we can see today is a readily available mechanism to produce content when given certain cues. This is likely an unavoidable part of the future toolset.

There is certainly a risk (or chance, depending on your mindset) this can take over large parts of repetitive work from a writing function too heavily focused on the audience perspective and not enough on the design intentions. The reasoning is that because this setup requires explicit cues across a knowledge horizon divide to get the intended results, it can potentially be replaced by artificial intelligence, which also operates on very explicit cues.

Sharing a knowledge horizon and making the right decisions with agency, however, is still far from achievable with AI. We can, instead, consider AI another useful tool in our arsenal, and use it to aid us given the cues we produce by understanding design intentions.

So how do you find out design intentions? If you’re lucky, your company is so well aligned that asking “so, what is it we do here?” gives you the answer.

If not, it may be that someone needs to think about where the answer got lost and how to align the company in understanding just what it does. You may even find yourself sparking a valuable conversation on some very deep seated aspects of company culture, values, and alignment on common goals, which for some time yet is another thing only humans can do.