I haven’t been writing much about writing lately, because I have a big! new! exciting! project coming up. I’ll tell you more about that later. However, this weekend I ended up in a twitter conversation about how I get myself unstuck when a piece of writing isn’t working, and I thought I’d share.
Abraham Lincoln apocryphally said that if he had six hours to fell a tree, he would spend 4 of them sharpening his axe. That’s how I feel about figuring out who I’m writing for. Once I can identify who my audience is, what they’re trying to do, and what they already know, the writing usually comes pretty easily.
The problem is that like sharpening an axe, persona-creation doesn’t feel like immediate forward progress.
Persona is what we say in a design and often marketing sense. It’s a description of a reader/user that frequently includes demographics, job duties, and experience level. I’ve been on teams that created personas, but they are often skewed to product design and not technical writing.
Ichiro and Microsoft
The persona I remember best is Microsoft’s Ichiro. Microsoft has an excellent paper from just before I worked there describing their theory. I can’t find a description of Ichiro, who was from the Longhorn period, but I can tell you about him. His picture was of the Mariner’s baseball player of the same name. He was a mid-level systems administrator, he worked for a small team, and he was the main Windows administrator. He already understood a lot of Windows technologies and networking, but some things, like full-disk encryption, were going to be new to him. He hated being “baby-talked”, but he was also allergic to anything that sounded like marketing spin — he just wanted to be able to set up a test system using minimal documentation and see how it worked before he would agree to roll it out to his users. A lot of the time I do technical writing, someone a bit like Ichiro is who I’m talking to, even now.
Theory of mind
As I’ve read more psychology, I think another way to describe this part of writing is theory of mind. Theory of mind is the ability to understand what another person knows and might be thinking. For example, theory of mind helps us understand that other drivers won’t be able to tell that we’re about to change lanes unless we signal. We know we are about to change lanes, but we project ourselves into the mentality of the driver behind us, and understand that they won’t know unless we tell them. In the same way, persona creation and usage is about understanding that other driver, that person who understands less than we do about the product, so that we can usefully and compassionately communicate with them.
The hard part of this, of course, is that you can’t know what anyone else is actually thinking. They might not be looking for turn signals, or they might be fiddling with the defroster. In an audience-analysis sense, you’re only going to be able to take a broad guess at what they do and don’t know. But still, a broad guess is better than assuming that they are exactly like you. After all, if they were, they would already know this stuff and you wouldn’t need to write (as much) about it.
(Yes, you still need to write documentation for yourself. Have you ever searched on an error and found the answer… and you were the one who wrote it? Give your future self that gift.)
Whose job is it?
That Twitter conversation was really interesting to me because the marketing writer I was talking to assumed that marketing would create the personas and share them with the technical writer. That has literally never been my experience, and I’ve been at this a while. At first, I thought about how great it would be if I didn’t have to do that work myself and could just consume known personas. But then I thought about how marketing personas, sales personas, and technical personas are all slightly but crucially differently focused.
For example, when sales is doing personas, they are trying to persuade people who know about us that we are the best choice. They are frequently dealing with management who doesn’t have their hands on keyboard, but consults with technical experts. They need ROI and cost-benefit analysis, and a high-level view of what we want their company to do. If I go into too much depth about OAUTH, I’m wasting their time.
When I am writing a technical persona, I am imagining someone like one of my friends, who is installing and managing a product they may or may not have helped pick. It’s not their only focus, and they have to plug it into a complex existing software stack. They don’t need ROI from me, they need installation and administration advice. If I tell them how much better we are than that other product, I’m wasting their time.
One of the fascinating parts of joining an early-stage startup is that it is legitimate and useful to care about and understand almost everything. When there were 40 employees, it totally made sense for me to give a sales training in the Mystical DevOps Words. As you grow, though, you need to change focus from breadth of knowledge to depth. My friends, there is so much domain knowledge in sales and marketing tools, trackers, analysis, drip campaigns, CRM… it’s every bit as complex as a development stack. But those areas of expertise are bigger than a person can rightly span. So we silo off.
In the DevOps world, siloing is axiomatically bad, we should all be working on the same product, supporting what we write, launching it ourselves, stuff like that. But in any sufficiently large organization (and it’s not very large), we need to have specialization. The point of breaking silos is not to have everyone know everything, but to have a shared common plane of communication. We need to be able to pass information and products from one area of specialized knowledge to another and get rapid feedback on it.
Sharing personas is one way for us to use this common plane. There shouldn’t be tech writer-created personas and marketing-created personas, there should be personas representing the installer, the purchaser, the user. But they shouldn’t be created by just one team, they should be created by every team that has experience and expertise, and then shared, updated, and referenced universally.
Where to start
So maybe you’re stuck on writing something and you would like to try this method to get unstuck. Here are some questions to answer to build yourself a persona.
- What are they trying to do?
- What do they already know?
- What are they worried about?
- Where do they sit on their org chart?
- What resources are they likely to use?
- Who do I know in real life that is like the person I’m writing for?
A persona can be as detailed as you find useful, but this might be a foundation. Give them a name, maybe even a stock photo. See if writing to this one particular person works better for you than “writing documentation” in the abstract.
Minneapolis DevOps Meetup