#write the docs

I gave a talk at Write the Docs this week, about how to write well for user interfaces. The video of it should be up soon - I’ll share it as soon as it gets posted. 

In the meantime, if you want some immediate steps you can take to make your user interface better, here are four ways to do it.

1. Don’t name things in your UI after things in your codebase

Or at least, be really careful before you do it. What your code does internally is rarely the same as what it does for users. 

Take the Cascade example. Internally, this button is adding a record. But for users, it’s letting them book a holiday.

Or the Google Drive example. Call something what it does for users, not how it works internally.

2. Explain what’s going on out loud

It’s hard to get phrasing right the first time, especially if you’ve not got much space. And if you’re not careful, it’s easy to write in a way that sounds robotic.

So start by explaining what your feature does out loud, in a sentence or two. How would you tell it to a person? Then write that down.

Because people speak like this:

Not like this:

Once you’ve got the meaning right, you can start cutting it down to the right size. Or if you need to, you can put your sentence into the UI, as embedded help.

3. Work out what’s blocking your users

Embedded help can get your users past obstacles. Work out what they need to know to complete their task, and put it in the user interface. 

If it’s essential information, and you’re leaving it out - how are they going to get past that point?

4. Write error messages that help users recover

The most important job of an error message is helping users move on from the error.

So tell them what they can do to fix the problem. If it’s just refresh or retry, say that. And don’t hide it away like this - make it clear like this. 

Be specific if possible - tell them exactly what they need to know to fix, avoid, or work around the problem. 

That’s not all

These are just a few tips, but there are so many more ways you can make the writing in your user interface better. I’m trying to put together as many examples as I can. 

I’ve just got back from speaking at Write the Docs, and I had a fantastic time. Thanks so much to everyone for your kind words about my talk - I’m so chuffed you all liked it. 

If you’re interested, you can take a look at my slides, or read the transcript I just typed up of what I could remember of what I said. The talks were filmed, so at some point I’ll be able to show you the video. I’m sort of looking forward to watching it, but sort of nervous too - it was my first real conference talk, and it was a bit of a blur, so I’ve no idea how I came across.

The runaway favourite bit of the talk - according to Twitter anyway - was this example of clearly expressing consequences:

Ideal error message: here's how this affects you. @baitman at #writethedocs pic.twitter.com/TUq9lGt2nU

— Elite Truong (@elitetruong) September 1, 2015

(thanks to elitetruong for tweeting it, and nickparker who it came from)

It’s funny, but it also makes a really good point. Clear language is so important if you want people to understand you. It’s the same point being made in this blog post - “use the words normal people would use”.

My 2014 Write the Docs talk, New Sheriff in Town

Now with a transcription!

My name is Heidi Waterhouse and I am a technical documentarian of almost 20 years now.

I have a talk that is in direct contrast to the other talks that you've already heard this morning and it's about the chaotic environment and how to bring a little order to it and impose some structure on it 

By the time we get to this point in our career most of us have specialized in one kind of thing or another like we specialize in security or we specialized in a particular writing tool or we specialize in an organization tape we might be started people are we might be big enterprise people but we have a thing that we do. 

My particular specialty is walking into a company that has never had a technical documentation person before and getting them sorta straightened out and then riding off into the sunset.

I imagine myself as a sheriff walking into a lawless Western town. I'm like I stride in and my spurs are jingling and my badge is shiny and I'm here to bring you some law and order because you need it now. You've gotten to the point where you're too big to just operate without it

So the first thing you want to do is get a star and the only star you really get is by being hired. You have now convinced the hiring manager that you're smart enough to handle their big thorny problem of not having any real documentation and you're just gonna have to hold that in your heart because no one else is going to believe in you. If they believed in documentation they'd already has somebody doing it.

You're going to have to overcome all of your imposter syndrome and all of your feelings like you don't know how to start documentation and just do it and believe that someone somewhere hired you to do this job.

You're here here because you can bring value to the job. You're here because you are an expert and you need to make sure that people understand that you have the authority to get the documentation out of their heads and onto paper.

The next thing we're going to do is set up shop. You open the old dusty Sheriff's Office or possibly it's an adjunct to the saloon and you walk in. The first thing that happens when you start a new job is people show you around, right? They're like "this is Heidi she's the new writer" and everybody goes "ooh a writer".

What I want you to do when you're doing this is make a map of the cubicles or chairs or desks that you're looking at with the names of people on them and what they specialize in because, I don't know about you, but when I meet twenty new people I remember none of them. I'm lucky if in the first three weeks I can remember my boss's name. "Oh, good, it's on an email, I guess I know who you are." But if you make a map of people in their specialties you can refer back to this in three weeks or six weeks when somebody says go talk to Janet, she knows about SQL. Now you know where Janet sits and you're not wandering around going, "Are you Janet? How about you?" It makes you look a lot more expert if you're like "Hey, Janet, talk to me about the SQL thing." 

You want to draw a map if your existing documentation and it seems funny that they would be documentation

if there isn't a documenter but there always is. There's always some weird little wiki the developers created, there's always some white paper that marketing has, there's always some bizarre conglomeration of poorly formatted documents somewhere. You need to draw a map to them and you need to make sure that you have access to them because people frequently forget to give you access to everything that you need, because they don't realize that being a technical documentation person means that you have to see everything in the company. Like maybe we'll leave out salaries, but otherwise you need to touch it all. And while you're waiting for them to set up your laptop in your permissions you should get to know the neighborhood. Like stop and read your competitors' documents. Almost none of us are working in a field so green that nobody else is doing what we're doing. So I work for Dell/Enstratius. We do multi cloud management, so I went out to look at who did cloud management and who did multi cloud management and I read some of infinite multitude Amazon Web Services document so that I knew what kind of environment I was getting into before I started asking really stupid questions. You can ask stupid questions, but it's nice if they're not the really stupid questions

I have a business card that says "Better and cheaper than having your developer write it."

[audience laughs]

And whenever I hand them out I get that response, right?

Because it turns out that developers will write things but it's expensive for them to do it because they can't be coding while they're doing it. It's better to have somebody who has specialized in writing to do the writing. Marketing people don't always write code and developers don't always write documentation and I write a really hacky web page. I've just accepted this. So now that you've been hired to be a specialist embrace that and say "Look at this is when I'm taking away from you"

So once you're there, you need to draw fast. Your documentation doesn't do any good if nobody is looking at it and if somebody goes around you while you're getting all figured out they're not going to trust that you're here to solve their problem. So take out your here trusty six gun and you draw fast  -- you don't have any time for frills.

I have done early documentation in Notepad. I've done early documentation and straight HTML. I have while waiting for the purchasing process to come through for documentation tools, I'll use sample products, like trial products which is a little awkward if they don't let you save, that's sometimes you have to do a little hacking, but the important thing for me is to deliver really early and show people that it's going to be valuable for them. I like to say that you'll get your precision between emergencies. So your precision is things like formatting and readability and localization and some really important things, but you can't get to those if nobody trusts you to put out the fire first. Say you're gonna have to think about what the most emergent emergency is and address that. 

The next thing we're going to do is save the townspeople. There's been a marauding group of bandits, possibly. So the first I'll to do to save the people is address their biggest internal pain point. 

When I started work at ABILITY Network I walked in and started talking to the customer support people. Then one day I noticed them receiving faxes that were filled with tiny tiny little rows on forms with hand-lettered 10 digit numbers. I'm like "what's that?" and they're like "Oh, that's the customer ID number, we can't do anything without the customer ID number and we misread it really often because they're teeny tiny hand-lettered numbers and I'm like "So, what you have to get faxes all with the hand-lettered numbers to let you do your job" and they're like "Yeah, that's how it goes." So the first thing I did was spent half an hour creating a PDF form that they could send out and get back and I didn't even make it smart enough to go into database, it was just that they could actually copy and paste out of it and that saved them two hours a day up front. Ever after that customer support was always on my side no matter what I wanted. They're like, "no, no, she's good, we can do that."

 Also doing that original pain point wins friends and influences people and quiets your own imposter syndrome so you don't feel like you're useless in the first three months because you haven't accomplished anything while you're learning this massively complicated new piece of software. 

The next thing you want to do is get people a structure to ask about things, and a way to get feedback and my favorite way to do this is to use an existing structure, which is bug tracking. I have declared that all documentation is equivalent to code and it needs to be published with code and it needs to be pushed with code and all the bugs need to be assigned to me as code bugs, so that I can fix them and track them and I have visibility and accountability. Because I do this, everyone can see where the problems are and what I'm working on and I have a nice little checklist like when I'm done writing massive conceptual documents on days that I'm just not that smart I can go through and check out of little bugs. And some developers and some customer support people, they will they will nitpick you to death like, did you really need to put a period there instead of a semi-colon? Really, guys? but you also get extremely valuable feedback on what is inaccurate and what is not working for them, so that's the internals. 

The externals -- for a while I worked at Microsoft and if you ever wondered if people read those little forms that are at the bottom of TechNet articles where you say "was this useful to you or do you wish it had something else the answer is, "Yes"," we read them and get evaluated on them and then we add them to our work list then go back and improve that." I know it feels like nothing ever changes but there's a lot of TechNet articles I'll and that that free flow of information back and forth really makes you feel like a more effective person.

Not all documents are for everyone, but if you can't identify which audience you're serving with the document you're writing the wrong document. If you can't visualize which townsperson you are saving with this particular document, then you're probably not saving anyone, you're probably just wasting time.

The next thing you want to do is check for scorpions. When I first wrote this I was thinking about people that I had had conflicts with when I'd walked into jobs earlier. So you're gonna want to check for scorpions which are situations and not people. Because if you start blaming people they'll start blaming you and you just have this terrible political problem. So what you want to do is look for hoarded documentation

I have a developer who I appreciate deeply and he was the guy who wrote all of the existing documentation and he wrote it in an impenetrable and inaccessible product, and I try not to believe that he did that on purpose. I'm not sure but we're going to go with the best possible explanation of "he liked it", I'll but he's really reluctant to let it go because he spent a ton of energy and effort on it and he's worried that I'm not technical enough to understand what's going on because he's been working on the product five years and I've been here less than a year so I understand why he is concerned about that and yet I look at it and go, "That structure is not really what I would have done."

Another thing that I have to worry about is stuff from the last sheriff. I'm talking as if there's never been someone doing documentation before but that's not always true. Sometimes there was a previous person and they have left behind feelings about technical documentation and sometimes cryptic arcane encrypted files and sometimes I don't know, weird trash that appears on the computer that you get and you need to look at that and see if any of its useful to you. You also need to look and see if you need to do damage control for how they've treated the team in the past. 

The next thing I do is I take all those people who are hoarding the documentation and I think of them as vigilantes. They're really interested in law, order, and good documentation but they're sort of operating outside the bounds of the law. So the the way to bring them and to gather them is to deputize them and say, "Hey, that was great documentation you did. I'm going to roll it into my tool that actually does localization and you're going to help me keep updating it and I want you to always proof it, like you are in charge of making sure that I am accurate on this. By deputising them you make me feel less like you're ripping their baby from their arms and more like you're becoming a collaborative team.

I found out last week that there's an entire training section in my company that I didn't know about and I said, "So where'd that come from?" and I'll he said well I think working on it for about half a year and I'm like, "okay, that's pretty good, it's pretty good, I might not have written in pure HTML with elastic search but okay." You're kind of a guy and I was kinda mad I was like why wouldn't anyone tell me about this? I said what percentage of your time is spent on this he said oh, 100 percent dedicated to it and like I came here is a technical writer nobody told me there was another technical writer! But he didn't think of himself as a technical writer he thought of himself as a customer support third-tier person who was writing all the implementation documents, and so he never thought of himself as part of the team. So now I've deputized him and I said you're part of the team, here's all the awesome things about being the team. Also give me all your source code. It worked out okay. 

The last thing we're going to do is build infrastructure. Once you have put out some other fires you want to settle into everyday life and a cadence so you have more resources to devote to building a structure so that you're not reinventing the wheel or the saloon every time you need a drink. You want to get templates and structure and things that you can spelled out and stub things in to say that you're not working as hard you have worked very hard in the first three to six months and months six to nine is more like building out. 

The town newspaper is your release notes. Let people know what you're doing on a regular basis -- go to the product demos, go to the scrum meetings. Be sure that documentation is seen as an integral part of the product and not a tacked on cost center.

One of the other things I do is go to the release meetings and say "so exactly when we going to incorporate documentation with that? I was just wondering are we going to push with the code or do I have a couple days afterwards if I'm just changing the text within these files and not the files themselves?"

And frequently the response okay this like "yeah, wow we're gonna do that all together." Bbut if I didn't show up to the meeting it would never occur to anyone the documentation is part of the code in the deliverable.

You set up a telegraph to talk to other sheriffs. Frequently if you are the new sheriff in town and the green field documentarian you are alone, you have nobody else to talk to you, and it's really isolating. So you need to set up a telegraph line the other sheriffs.

This [indicates audience] is an example of how we're communicating with each other and find peers that are going to support you when you have rants that are specific to technical documentation

One of the signs that a town has grown from happenstance into a place where people are planning to live is something called platting. In a plat, founders designated spaces for schools and graveyards, parks and civic institutions, even universities. Every organization has varying needs but there are significant plat sections that you can look at and make sure that you covered in your creation of this town.

You want to know that customers can use your product.

You want to know that whoever is installing your product can configure it.

You want to know that advanced users can customize your product. Frequently this is stuff like API documentation, so it's not for everybody but you want to know that they can use the data and use the product in the way that they need to use it.

You want to know that everyone can fix problems when something goes wrong. If you don't have a way to solve problems, people will create it on their own -- they will go to your user board or to stackoverflow and write it on their own and then you can steal it back from them, but it's better to provide them fixes in the first place.

And you're going to need a reference guide because eventually it will get too big for you to remember all the things that are switches and knobs and buttons and some people would rather just look up that one thing than have to go through all of documentation to find it. You need an extremely searchable reference guide.

Plan for succession! You may win the lottery or you may get shot by banditos or laid off. Any of the skin things could happen. Please don't have all of your technical documents on your personal computer and your locked repository, because the next person who comes in is going to hate you forever. Remember that you are part of the code base and you need to be versioning and submitting and publicizing exactly the same as they are, because someone some day is going have to come in and pick up where you left off.

Another thing, the last thing that I think you should think about is: sheriffs are part of the town -- they live in the town, they send their kids to school, they're really invested in it. Texas Rangers ride in to town, shoot the bad guy, and leave. You should think about whether you want to be a sheriff or Texas Ranger. I'm evolving from Texas Ranger in to sheriff -- I'm spending longer and longer with companies once I set them up, but I had a great career where I'd stay eight to 12 months with the company, get them straightened out and then leave. It's a valid career option and if you want to talk to me about it I would be happy to speak to you about it. It's a really interesting and exciting way to get to learn a lot of new things

I think green field writing is some of the most exciting work there is in our industry -- you get to come up with the architecture and the design and the delivery and everything about how your technical documentation works. You get help frustrated newbies and grizzled veterans get their job done, and you get to do it all without any conversion problems!

I'm always happy to talk about the speciality and I hope you will ask any questions you have about finding these jobs, starting them out, and not letting them burn you out.

This is my contact information I think we have a couple minutes for questions, if anybody has any questions I'd be happy to answer them.

No questions. Okay you don't have a couple minutes for questions.

Question: Hey, love your analogy. What is green field documentation?

Answer: Oh, so! Mister Christiansen who talked about permaculture is sort of working on the opposite side of the field this when you walk into a pasture and it hasn't been plowed to be a farm field. It's untouched, it's virgin ground it's not, there's nothing there

Question: It sounds like you going to situations sometimes where there's a legacy that he said maybe resentment against the person you're some sort of conflict and and do you have favorite techniques for breaking down those barriers or sessions that you kinda go through to get communication going again?

Answer: own frequently it's me finding their pain point in solving it. Always when I walked into the situation what they felt like is that the writer didn't listen to that, that the writer was not paying attention to what they were saying about their expertise in the product, and so the first thing I try and do is being really good active listener are I like to sit down with the devops people and have them install a working environment for me. Like not info for me but walk me through installing a working environment and take notes on it and when they see me write up how to install a working dev environment they've realized that I just saved them all this tedious onboarding for the next five or six people and and then they're a lot more cooperative because they realize that I'm actually here to add value to their life.

Write the Docs 2014 (Links)

Videos of All The Talks!

Daniel Lemke’s Notes

Andrew Spittle’s Notes

Marko Gargenta’s Notes

Dianne Stevens’s Notes

Write the Docs 2014 (Day 1)

[Note: Giant conference notes info-dump behind the link. These are raw notes, I've not really cleaned them up at all, but wanted to share in case others find it useful.] (more…)