Empathy for the Dev: Avoiding common pitfalls when communicating with developers

In my profession as a developer advocate, convention organizer, and technical author, I’ve spent lots of time serving to builders talk. I’ve seen what works and what doesn’t. When communication fails, it’s actually because the developer is speaking to themselves, to not the listener—a failure of empathy.

Mostly, I see this empathy fail spectacularly in software program documentation. Documentation permits builders to go deep on the technical points of the product they constructed, one thing that they spent months if not years of their life creating. All too typically, although, builders go deep on the incorrect issues, focusing extra on the product itself than on how individuals will use it.

On this article, I stroll via the highest three widespread errors I see when builders write documentation, and describe how these widespread errors will be fastened via empathizing together with your customers.

Forgetting that builders need to do one thing

In her guide Badass: Making Users Awesome, Kathy Sierra factors out that only a few customers need to be utilizing software program. As an alternative, they need to do the issues that software program allows. For instance, do you need to use a cellular test deposit app, or do you need to deposit a test and the cellular test deposit app is the way you do this? 

Software program—and by extension, software program documentation—is friction in our customers’ lives. Customers don’t need to purchase your software program, and so they don’t need to learn your documentation—they only need to have their issues solved. Understanding and empathizing with it will make it easier to create higher software program merchandise and write higher software program documentation.

One option to deal with that is to create use instances for the merchandise and options you develop. A use case ought to include: 

  • Your consumer persona: Who your consumer is and what they already know
  • Your consumer’s targets: What your customers need to do together with your product

A use case describes how somebody makes use of your software program to attain a selected aim. As you recognize from your individual expertise, not each software program consumer is identical—all of us arrive with completely different psychological fashions, earlier experiences, and wishes. Create a number of sentences for every of the bullet factors above that will help you scope your challenge and empathize together with your consumer. Then, if you begin writing documentation, you’ll know who you’re writing for. 

An instance of consumer personas is software program that has each administrator and consumer roles. The administrator does issues like configure software program for a company atmosphere, arrange consumer permissions, and replace software program as wanted. An administrator wants rather more intensive setup and configuration directions than the each day consumer. The each day consumer wants extra product-level documentation than the administrator. An administrator doesn’t have to know the best way to copy a number of columns throughout sheets, and a consumer doesn’t have to know the best way to configure SSO. 

Good documentation means writing to be used instances that match the wants of your software program’s likeliest consumer personas. An administrator wants documentation like “Configuring with a proxy” and “Populating entry management lists,” which a consumer doesn’t. Every use case solutions a query that pertains to somebody’s precise work: “How do I set up this? How do I safe this? How do I work out what went incorrect?”

It’s straightforward to be distracted by all of the issues that you just need to inform somebody in a selected use case. Think about that 80% of the individuals studying your documentation solely need or want 20% of what you recognize. Earlier than you cowl edge instances and strange conditions, be sure you first deal with the wants of most of your customers.

The “affirm button” downside

A standard mistake we make when writing software program documentation is to explain the what of the interface, as an alternative of the how of a consumer’s workflow. I confer with this because the affirm button downside. “Click on the Affirm Button to verify” is technically documentation, however it’s not serving to anybody accomplish a job; it’s simply describing the interface. You would possibly suppose this occurs much less typically with extra developer-focused paperwork, however I might guess that in the event you have a look at your API docs, there’s a “Person Identify” discipline with an outline that claims “Person Identify.” 

The consumer journey

The consumer journey is how somebody with out your expertise with the product encounters it. This journey could be a helpful option to write and arrange your content material. This logic offers us the “Fast Begin” information. Whoever offered you the software program, digicam, or blender that you just simply unpacked is aware of that you just’re not going to learn all of the documentation, so they’re providing you with the naked necessities as quickly as you open the field. 

As you get extra accustomed to the instrument and need to transcend the automated settings, you’ll dig into the finer particulars described within the full documentation. When you have an issue or need a function, you’ll attain out to help. Whenever you get sufficient info, you cease. Getting somebody solely the knowledge they want, on the right time, is extra necessary and helpful than studying all of the paperwork. 

Ultimately, no software program (besides possibly COBOL) is immortal, so there comes a time when a consumer stops utilizing the product and the software program is deleted, uninstalled, or outdated. Your documentation plan wants to incorporate what occurs to paperwork after their helpful lifespan. Have you learnt what occurs to your product after adoption? Are you able to describe it? Do individuals have a option to get their information out?

Transport your org chart 

Lastly, there’s the issue described by Conway’s Law: don’t ship your org chart. What we imply by that is that software program (and documentation) is written in response to the organizational constructions that we work in, and never within the use patterns that customers want. If the installer group is staffed in a different way than the troubleshooting group, a consumer’s wants would possibly fall into the hole between groups, with neither group answerable for troubleshooting a consumer’s downside.

Every group is writing what they know greatest—their very own function—with out documenting how the options, they solely write about that and never about how the options interoperate or how they may circulate into one another within the area of a consumer’s workday.

The ensuing documentation seems one thing like:

  • Flagship product:
    • Characteristic 1 documentation
      • Overview of Characteristic 1
      • Tips on how to use Characteristic 1
    • Characteristic 2 documentation
      • Overview of Characteristic 2
      • Tips on how to use Characteristic 2
    • Characteristic 3 documentation
      • Overview of Characteristic 3
      • Tips on how to use Characteristic 3

This construction is sweet and neat on the floor, however it requires customers to sift via and assemble an excessive amount of differentiated content material to resolve their issues. Whenever you arrange by how one thing is constructed, it doesn’t relate to what a consumer must know proper now: the best way to resolve their quick downside.

In case your product has a number of completely different consumer personas and consumer journeys, it’s generally tough to coordinate these transitions. I’ve discovered, although, that in the event you give individuals a persona and a narrative to comply with via the product, they perceive why it’s worthwhile to write for the duties individuals have as an alternative of the best way the product was created. People like tales and shall be empathetic if they’re given a means to take action. You simply want to assist create that connection between the software program you write and the individuals who will use it.

Empathetic documentation is profitable documentation

Cultivating empathy for the individuals utilizing your product is essential to its success, and documentation is one space the place you may exhibit that empathy. Considering fastidiously about who your customers are and what they want out of your documentation not solely makes the writing course of simpler and extra intuitive, but in addition helps customers derive extra worth out of your product.


For those who’d like extra writing recommendation tailor-made for builders, take a look at the guide I co-authored: Docs for Developers: An Engineer’s Field Guide to Technical Writing.

Tags: documentation, empathy

More Posts