In my profession as a developer advocate, convention organizer, and technical author, I’ve spent numerous 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 usually, although, builders go deep on the improper issues, focusing extra on the product itself than on how individuals will use it.
On this article, I stroll by means of the highest three widespread errors I see when builders write documentation, and describe how these widespread errors will be fastened by means of empathizing along with your customers.
Forgetting that builders wish to do one thing
In her e book Badass: Making Customers Superior, Kathy Sierra factors out that only a few customers wish to be utilizing software program. As a substitute, they wish to do the issues that software program permits. For instance, do you wish to use a cell test deposit app, or do you wish to deposit a test and the cell 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 wish to purchase your software program, they usually don’t wish to learn your documentation—they simply wish to have their issues solved. Understanding and empathizing with it will enable you to create higher software program merchandise and write higher software program documentation.
One solution to tackle 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 objectives: What your customers wish to do along with your product
A use case describes how somebody makes use of your software program to attain a specific aim. As from your personal expertise, not each software program consumer is identical—all of us arrive with completely different psychological fashions, earlier experiences, and wishes. Create a couple of sentences for every of the bullet factors above that will help you scope your venture and empathize along with your consumer. Then, whenever 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 setting, arrange consumer permissions, and replace software program as wanted. An administrator wants far 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 must know the right way to copy a number of columns throughout sheets, and a consumer doesn’t must know the right 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 improper?”
It’s straightforward to be distracted by all of the issues that you just wish to inform somebody in a specific use case. Contemplate that 80% of the individuals studying your documentation solely need or want 20% of what . Earlier than you cowl edge instances and weird conditions, be sure to first tackle the wants of most of your customers.
The “affirm button” downside
A typical 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 seek advice from 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 may suppose this occurs much less usually with extra developer-focused paperwork, however I might guess that when you take a look at your API docs, there’s a “Consumer Identify” discipline with an outline that claims “Consumer Identify.”
The consumer journey
The consumer journey is how somebody with out your expertise with the product encounters it. This journey generally is a helpful solution to write and arrange your content material. This logic offers us the “Fast Begin” information. Whoever bought you the software program, digital camera, 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 supplying you with the naked necessities as quickly as you open the field.
As you get extra accustomed to the instrument and wish to transcend the automated settings, you’ll dig into the finer particulars described within the full documentation. When you’ve got an issue or need a function, you’ll attain out to help. Whenever you get sufficient data, you cease. Getting somebody solely the knowledge they want, on the appropriate time, is extra necessary and helpful than studying all of the paperwork.
In the long run, no software program (besides perhaps COBOL) is immortal, so there comes a time when a consumer stops utilizing the product and the software program is deleted, uninstalled, or outmoded. Your documentation plan wants to incorporate what occurs to paperwork after their helpful lifespan. Are you aware what occurs to your product after adoption? Are you able to describe it? Do individuals have a solution to get their knowledge out?
Delivery your org chart
Lastly, there’s the issue described by Conway’s Regulation: don’t ship your org chart. What we imply by that is that software program (and documentation) is written in accordance with the organizational buildings that we work in, and never within the use patterns that customers want. If the installer staff is staffed in a different way than the troubleshooting staff, a consumer’s wants may fall into the hole between groups, with neither staff chargeable for troubleshooting a consumer’s downside.
Every staff 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 could circulation into one another within the house of a consumer’s workday.
The ensuing documentation seems one thing like:
- Flagship product:
- Characteristic 1 documentation
- Overview of Characteristic 1
- Methods to use Characteristic 1
- Characteristic 2 documentation
- Overview of Characteristic 2
- Methods to use Characteristic 2
- Characteristic 3 documentation
- Overview of Characteristic 3
- Methods to use Characteristic 3
- Characteristic 1 documentation
This construction is good and neat on the floor, however it requires customers to sift by means of and assemble an excessive amount of differentiated content material to unravel their issues. Whenever you arrange by how one thing is constructed, it doesn’t relate to what a consumer must know proper now: the right way to resolve their speedy 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 when you give individuals a persona and a narrative to comply with by means of the product, they perceive why you have to write for the duties individuals have as an alternative of the way in which the product was created. People like tales and will probably be empathetic if they’re given a approach 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 vital to its success, and documentation is one space the place you may reveal that empathy. Considering rigorously 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 additionally helps customers derive extra worth out of your product.
—-
When you’d like extra writing recommendation tailor-made for builders, try the e book I co-authored: Docs for Builders: An Engineer’s Subject Information to Technical Writing.
Tags: documentation, empathy
