In my career as a developer advocate, conference organizer, and technical writer, I’ve spent a lot of time helping developers communicate. I’ve seen what works and what doesn’t. When communication fails, it’s often because the developer is talking to themselves, not to the listener—a failure of empathy.
Most commonly, I see this empathy fail spectacularly in software documentation. Documentation allows developers to go deep on the technical aspects of the product they built, something that they spent months if not years of their life creating. All too often, though, developers go deep on the wrong things, focusing more on the product itself than on how people will use it.
In this article, I walk through the top three common mistakes I see when developers write documentation, and describe how these common mistakes can be fixed through empathizing with your users.
Forgetting that developers want to do something
In her book Badass: Making Users Awesome, Kathy Sierra points out that very few users want to be using software. Instead, they want to do the things that software enables. For example, do you want to use a mobile check deposit app, or do you want to deposit a check and the mobile check deposit app is how you do that?
Software—and by extension, software documentation—is friction in our users’ lives. Users don’t want to buy your software, and they don’t want to read your documentation—they just want to have their problems solved. Understanding and empathizing with this will help you create better software products and write better software documentation.
One way to address this is to create use cases for the products and features you develop. A use case should contain:
- Your user persona: Who your user is and what they already know
- Your user’s goals: What your users want to do with your product
A use case describes how someone uses your software to achieve a particular goal. As you know from your own experience, not every software user is the same—we all arrive with different mental models, previous experiences, and needs. Create a few sentences for each of the bullet points above to help you scope your project and empathize with your user. Then, when you start writing documentation, you’ll know who you’re writing for.
An example of user personas is software that has both administrator and user roles. The administrator does things like configure software for a corporate environment, set up user permissions, and update software as needed. An administrator needs much more extensive setup and configuration instructions than the daily user. The daily user needs more product-level documentation than the administrator. An administrator doesn’t need to know how to copy multiple columns across sheets, and a user doesn’t need to know how to configure SSO.
Good documentation means writing for use cases that match the needs of your software’s likeliest user personas. An administrator needs documentation like “Configuring with a proxy” and “Populating access control lists,” which a user doesn’t. Each use case answers a question that relates to someone’s actual work: “How do I install this? How do I secure this? How do I figure out what went wrong?”
It’s easy to be distracted by all the things that you want to tell someone in a particular use case. Consider that 80% of the people reading your documentation only want or need 20% of what you know. Before you cover edge cases and unusual situations, make sure you first address the needs of most of your users.
The “confirm button” problem
A common mistake we make when writing software documentation is to describe the what of the interface, instead of the how of a user’s workflow. I refer to this as the confirm button problem. “Click the Confirm Button to confirm” is technically documentation, but it’s not helping anyone accomplish a task; it’s just describing the interface. You might think this happens less often with more developer-focused documents, but I would guess that if you look at your API docs, there's a “User Name” field with a description that says “User Name.”
The user journey
The user journey is how someone without your experience with the product encounters it. This journey can be a useful way to write and organize your content. This logic gives us the “Quick Start” guide. Whoever sold you the software, camera, or blender that you just unpacked knows that you’re not going to read all the documentation, so they are giving you the bare essentials as soon as you open the box.
As you get more accustomed to the tool and want to go beyond the automatic settings, you’ll dig into the finer details described in the full documentation. If you have a problem or want a feature, you’ll reach out to support. When you get enough information, you stop. Getting someone only the information they need, at the correct time, is more important and useful than reading all the documents.
In the end, no software (except maybe COBOL) is immortal, so there comes a time when a user stops using the product and the software is deleted, uninstalled, or superseded. Your documentation plan needs to include what happens to documents after their useful lifespan. Do you know what happens to your product after adoption? Can you describe it? Do people have a way to get their data out?
Shipping your org chart
Finally, there’s the problem described by Conway’s Law: don’t ship your org chart. What we mean by this is that software (and documentation) is written according to the organizational structures that we work in, and not in the use patterns that users need. If the installer team is staffed differently than the troubleshooting team, a user’s needs might fall into the gap between teams, with neither team responsible for troubleshooting a user’s problem.
Each team is writing what they know best—their own feature—without documenting how the features, they only write about that and not about how the features interoperate or how they might flow into each other in the space of a user’s workday.
The resulting documentation looks something like:
- Flagship product:
- Feature 1 documentation
- Overview of Feature 1
- How to use Feature 1
- Feature 2 documentation
- Overview of Feature 2
- How to use Feature 2
- Feature 3 documentation
- Overview of Feature 3
- How to use Feature 3
This structure is nice and neat on the surface, but it requires users to sift through and assemble too much differentiated content to solve their problems. When you organize by how something is built, it doesn’t relate to what a user needs to know right now: how to solve their immediate problem.
If your product has multiple different user personas and user journeys, it’s sometimes difficult to coordinate those transitions. I have found, though, that if you give people a persona and a story to follow through the product, they understand why you need to write for the tasks people have instead of the way the product was created. Humans like stories and will be empathetic if they are given a way to do so. You just need to help create that connection between the software you write and the people who will use it.
Empathetic documentation is successful documentation
Cultivating empathy for the people using your product is critical to its success, and documentation is one area where you can demonstrate that empathy. Thinking carefully about who your users are and what they need from your documentation not only makes the writing process easier and more intuitive, but also helps users derive more value from your product.
----
If you’d like more writing advice tailored for developers, check out the book I co-authored: Docs for Developers: An Engineer’s Field Guide to Technical Writing.