Empathy for the Dev: Avoiding common pitfalls when communicating with developers
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
- Feature 1 documentation
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.Tags: documentation, empathy
Excellent reminder Heidi. Sharing this in “my circle.” Thank you.
This is very true and helpful. Thanks for sharing.
The key is empathy, evaluating the value added by the document from the scope of the readerr and not the author
This post would have been better titled “Empathy for the User: Avoiding Common Pitfalls when Communicating (as a Developer)”.
If it had, I for one probably would never have clicked on the link. So I’m guessing the misleading name was deliberate.
I would say “Avoiding Common Pitfalls when writing documentation”.
Same thing here … Almost gave the link to my managers. I hope it wasn’t deliberate, but i’m not sure …
Same. I was hoping for some sage advice to help me communicate to the devs on my team (especially one that is proving difficult to work with!). Maybe it illustrated expectation vs reality 😀
It does not compute near “without documenting how the features, they only”. It may be a run-on sentence. This does not need to be published. It is more important that action is taken.
Agree with a previous comment. The headline is mistaken. This is about communicating with end users, not empathy for developers.
The perfect title would have been “Empathy for the Devel.”
Right, it alludes to Rolling Stones song title “Sympathy or the Devil”. People need to study The Classics! 🙂
Tech writer from New Zealand here, Heidi. I really enjoyed your article and it made perfect sense to me. I’ve been writing end-user help for users of payroll software for several years and am now moving into developer docs, including documenting REST APIs. I will definitely bookmark your article and refer to it again.
I think you have very good site. I have used some from your site and i think they are good things.
Readers who are nitpicking on the wording, and the difference between users and developers, are missing an important point: Developers are themselves users a lot of their working time, and their minds work just the same, though on a different, more technical level. This article can as well be applied to providers of libs, tools, utilities, internal facilities and their documentation. I’ve just shared the link with my team, for current reasons.
And speaking of classics, “Don’t Make Me Think” is probably THE classic on that subject.
Please go on Heidi!
Please don’t tell me your book is about catering to people who don’t want to think.
This articles talks about what the user wants from the developer. What about what the developer wants from the user?
It talks about having empathy for the user. What about empathy for the developer?
It talks about empathy failure on the part of the developer. What about empathy failure on the part of the user?
Just in case you actually do care about what the developer wants- this is what she / he wants : Not to be complained to or criticized when the software doesn’t work the way the user wants it to. At least not when the software is doing what it’s supposed to, but the user didn’t bother to read the documentation to know that. Suggestions and feedback? Cool. Complaints and criticisms due to user error? Not cool.
A developer can be friendly and helpful, sure. But it sure gets hard when people don’t respect the developer’s time, and think that helping other people learn / use software is their main job. Remember you’re not the only user of the software. If every user took 5 minutes of the developer’s time, that often amounts to no time left for the developer to do their actual job- developing and maintaining the software.
Here’s a perfect world- Someone besides the developer decides all the details of what the software needs to do, develops documentation for it, and takes all feedback, critiques, bug reports, etc., and improve the documentation with it, with change tracking, a change log, etc., and submits it to the developer. That one person is the only one who talks to the developer directly about work stuff- or at least is the only person the developer is accountable to for work stuff. The developer’s job is to make the software, and the other person’s job is everything else this article talks about.