Guest post: UX Booth

I wrote a 2018 User Experience Prediction at UX Booth. Amy Grace Wells asked me what I thought was going to be a leading theme in UX in the next year, and I said, “better accessibility”. I think that’s both a serious prediction and a hope, because there is never enough accessibility, but I also think we are getting better.

So many things that are designed for accessibility, but that we don’t always understand that way when they happen, and frequently we mock them as lazy or luxurious. Backup cameras on cars seem silly – why not just turn around? Until you physically can’t turn around, and then you realize how much they matter. Pre-chopped vegetables, electric can-openers, and velcro shoes seem laughable – unless you’ve ever been unable to hold something in both hands at once. In the same way, building web and mobile apps to respond to a variety of command styles may not occur to us if our fingers are nimble or our voices clear, but will matter immensely to people who are not in that category.

Since before I was employed at LaunchDarkly, I’ve been fascinated by the ability that feature flags offer designers to customize user experience. We haven’t had a good test case yet that I know of, but it will come, and I’m looking forward to it.

Peeled oranges in plastic containers

Pre-peeled oranges for accessibility

Post on How to nail a tech writer job inteview

I was excited to write another post for

How to nail a tech writer job interview

It’s an extension of a twitter rant I went on a bit ago, about how important it is to know certain things about interviewing as a technical writer, but no one is teaching them, from what I can tell.

  • What kind of samples should you offer?
  • What is ethical to use as a sample?
  • What is a reasonable (and unreasonable) writing test?
  • How do you talk about team projects or work for hire?

I’m already in discussions with the team about a follow-up, based on my New Sheriff In Town talk. That one will cover how to walk into a new position and figure out what to write first.

If you’re interested in more content on interviewing, Carol Smith and I are putting the finishing touches on a workshop about all the not-code parts of a technical interview. You’ll be able to read more about that in The Recompiler soon, and of course, I’ll post about it here.


Response to: Modern Technical Writing, by Andrew Etter

I’ll be honest. I’m a little mad I didn’t write this book. It’s clear, lucid, and pithy. I agree with much of the philosophy of minimal tooling and semantic separation of form and content.

Etter says,

Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms.

To which I say, yes, yes! I’ve been saying, speaking, thinking, writing the same message. It’s so much more efficient to have good docs. I also agree that good technical writing (about software) is mostly about testing and research, and the time spent with the product should get distilled down into an understanding and then and only then transmuted into words.

He also says that it is much easier to answer the how of software, rather than the why, but you must answer the why to really write something useful. His points on lightweight markdown, rapid publishing, and internationalization are all exactly on-point.

My quibble with this book (and it is only a quibble, not a full-fledged criticism) is that there is a section missing, and it is the section on user motivation. You can write the most beautiful, terse, lightweight, well-indexed documentation in the world, but if you’re not driving toward what the user needs in every sentence, they’re not going to read it. The user doesn’t want to be reading documentation. Reading documentation is the opposite of doing something interesting with software. It’s filling up the car before an amazing road trip, it’s an impediment. And until we as writers realize that, we’re going to continue to write too much, for the wrong people, at the wrong time.

Etter is very clear up front that this is only about software documentation, as practiced in software companies. But there are a lot of people in technology, the majority of people in technology who don’t work building software per se.

It’s not Etter’s fault that we forget this. We have build ourselves a cozy little ecosystem, and if I told you I worked for a company doing Hadoop or containerization or financial APIs, you would understand that I worked for a software company. But I have also worked for a health insurer, a social media empire, a durable goods manufacturer, a commodities broker. I wrote about software, I wrote about our products, I made decisions about security and metadata and the location of quick start guides – as a technical writer. There’s a big non-software world out there that we keep forgetting to talk to and learn from.

What would this book look like if we didn’t assume that software was a service, that our users were relatively computer-savvy, that we were not the only kind of writers in the world? I keep coming back to this article by the Nielsen Norman Group: The Distribution of Users’ Computer Skills: Worse Than You Think. Jakob Nielsen, trenchant and brilliant as usual, points out that we keep designing things for ourselves, and we are really, terribly, fearsomely wrong about that.

You = Top 5%–8%

The main point I want to make is that you, dear reader, are almost certainly in the top category of computer skills, level 3. In the United States, only 5% of the population has these high computer skills. In Australia and the UK 6% are at this level; in Canada and across Northern Europe the number increases to 7%; Singapore and Japan are even better with a level-3 percentage of 8%.

Overall, people with strong technology skills make up a 5–8% sliver of their country’s population, whatever rich country they may be coming from. Go back to the OECD’s definition of the level-3 skills, quoted above. Consider defining your goals based on implicit criteria. Or overcoming unexpected outcomes and impasses while using the computer. Or evaluating the relevance and reliability of information in order to discard distractors. Do these sound like something you are capable of? Of course they do.

What’s important is to remember that 95% of the population in the United States (93% in Northern Europe; 92% in rich Asia) cannot do these things.

You can do it; 92%–95% of the population can’t.

What does this simple fact tell us? You are not the user, unless you’re designing for an elite audience. (And even if you do target, say, a B2B audience of nothing but engineers, they still know much less about your specific product than you do, so you’re still not the user.)

I’ve seen people take this argument and assume that means we need to produce more videos, and I think that’s the wrong assumption. I think that what Etter, and I, and you, need to do is remember that the world is bigger than “software development” and writing for the people in the big world is the next level, something we have to strive for, rather than staying in our small and shrinking tidepool of high-tech and software.

Guest post: SysAdvent!

I wrote a pitch for SysAdvent and got it accepted, and then realized that it was due right in the middle of all my travel, so it’s a good thing my volunteer editor was willing to work with me on the timing.
Day 17 – Write It Down or Suffer the Consequences

This article has a lot in common with my Fear of the Bus lightning talk, but I have a little more time to flesh out the ideas and connect them. I hope you enjoy my take on how to do minimally invasive documentation for systems and not just software.

SysAdvent Logo

SysAdvent Logo

Many hands make a messy wiki

In October, I attended HydraConnect. To my relief, it was not a networking event for evil comic book characters, but rather an in-depth conference for people running the Hydra software, which is used in higher education (and other library-like places) to organize digital collections.

When I walked in the first day, I didn’t even know that much. I’d been contracted to attend the unconference days and add a technical writing perspective to a distributed open source project. I wasn’t sure if I would actually add value, but it seemed worth the experiment, and I learned and taught a bunch of things, which I will summarize here.

Your documentation needs a lifespan

There are two problems in software documentation:

  • Getting anyone to do it.
  • Getting rid of it.

This is especially true in distributed open-source projects because there are many people contributing, but seldom a firm hand disposing. My proposal is that you PROGRAMATICALLY make your wiki pages expire after a year to trim down your documentation cruft and help keep all your docs accurate.

Scenario: You sit down and check your dashboard. Three notices appear for pages expiring this week. You click on the link to the first one. It is a workaround for a bug that has been patched. Do nothing. This data should die. The second one is a valuable tutorial that you know people still use. You check to make sure it still looks accurate, and click the Renew button. Safe for another year. The third link leads to a requirements page that should get updated now that some of the software mentioned is too old to be supported. You edit the page to be accurate and click Renew.

I came up with this idea because of some work I’d done years ago with people interested in sunsetting personally identifiable data. This is not quite the same as Right to Be Forgotten, it’s more that just because we can store an effectively infinite amount of data doesn’t mean we should.

Do you think there are actually 36 million people working for the government? No, but anyone who has worked for the goverment in the age of data had their information collected and NEVER PURGED. A huge part of that vulnerability is because our data never expires.

Data should have a lifespan. Technical data should get reviewed every year. Credit data should roll off after seven years. Your entire childhood posting history should get wiped when you turn 18. If we were more mindful about this, we’d have cleaner docs AND fewer horrifying data breaches.

Your documentation should get treated like code

This is not a new concept, but it’s especially useful for distributed teams.

  • Keep your docs in a repository
  • Write bugs against them
  • Include them as part of features
  • Write tests against your docs. If a novice user can’t follow your directions to do a task, you are not done. You can also use your docs as a test. If you follow the directions and the thing doesn’t install, you need to find out where the problem is.

Good examples are as important as good explanation

I could spend 300 words explaining to you how I like my peanut butter and jelly sandwiches made (toast, raspberry jam), or I could hand you my sandwich and let you see for yourself how it works.

Many people need that concrete example to understand what is possible for them to accomplish. Some of my current favorite documentation are the Swagger API docs. They are not very wordy at all, super minimal, but you get a sample site that works, and then you can play with it, and the documentation is all baked into that. I can see how it’s supposed to work, instead of following a process and hoping I get it right enough to work.

Search is how new users learn

When you get stuck on a new problem, especially if you’re not sitting next to someone who can answer your question, what do you do? Most developers and IT people I’ve talked to Google it, almost as a spinal reflex. If you are not doing internal analytics and designing internal SEO around that, then Stack Overflow is doing a better job supporting your product than you are. That’s not catastrophic, but it’s not great, either.

Set up analytics on your wiki, your web page, your help, wherever you are storing your documents, and start watching the search terms people are using. If your documents don’t answer the questions, write more. If the queries are using the wrong language, add better tags and keywords to your documents so they’re findable. I’m really glad someone wrote that, but it is a tiny bit worse than useless if no one ever finds it.

Drawing the elephant is better than explaining one piece at a time

Do you know the story about the six blind men trying to explain an elephant? One gets hold of the ear, and says, “I percieve that an elephant is very like a fan.” Another finds the elephant’s flank and deems it wall-like. Each person has a different experience of the elephant and even talking to each other, they can’t conceptualize “elephant”. Is your documentation like those people talking to each other? Has anyone provided a picture or description of the elephant? High-level conceptual topics are both difficult to write and technically complicated. You have to understand both the audience and the product. But without that description, you just have a bunch of disparate tasks.

Which leads me to my next point…

Context increases compliance

Knowing why I’m doing something makes me much better about doing it. I don’t let strangers poke me with needles, but I do get my flu shot, because I have enough context to know that it is the lesser evil.

If you’re asking people, especially volunteers, to do work, you need to be able to explain how their effort is going to be a benefit to the organization. It doesn’t need to be An Epic Explanation, just a little something to guide people. “Let’s get these chairs stacked out of the way for the karate class coming in.” is much more contextual that “We need these chairs in stacks of four.” Be sure you are providing acessible context for the product and the project.


Distributed teams that are not specialist writers can still create documentation, but they need to get rid of old docs and they need to have a clear vision of what they are doing and why.


I really enjoyed the experience of the conference. Badges with pronouns! Other women, of all ages. But I also enjoyed being a technical writer at people. I’d like to do that again, for other projects that can’t afford a writer but do need a writer perspective

(crossposted and updated from LinkedIn, thanks to Sumana for the nudge)

The Seven Righteous Fights: Overview

This is a series derived from my popular talk “The Seven Righteous Fights”. It’s not an exact transcript, but I think having a written form to refer people to greatly increases accessibility and gives me room to expand my thoughts in a way that is not compatible with speaking.

There are seven fights that I have over and over again, whenever I start at a company. The more software you build, the more it’s obvious that there are seven fights that it will alway pay to have.

My background as a writer means that I am trained to perform a lot of analysis and synthesis. If I don’t understand the product from value proposition through implementation, it means that I am not the writer I want to be. I call it being a full-stack writer. The problem with having all this training in analysis is that you can’t exactly turn it off. I don’t stay in my lane well, I can’t notice problem that only fall into the narrow category of “documentation”. They’re all documentation problems, they’re all software problems, they’re all design and usability problems.

I’ve worked for roughly 15 companies and my conclusion is that when we create something new, we tend to make similar mistakes every time. This is probably because we all tend to settle in a comfortable stage of product development. Some people prefer mature products, some people like the very beginning and hate the mature product maintenance. But that preference means we don’t understand pain points that happen at other stages.

I’m an early-stage person. I love writing the first version of documentation. I love that green field and that new product smell. But I have done enough mid-stage stuff to know the emergent consequences of early-stage decisions. And like everything you’ve ever read about compound interest, early mistakes compound until they are enormous.

I was working with a startup that was pushing super hard to get their product ready to demo at a big industry conference. They were stripping off every feature they didn’t absolutely need in order to make sure they made their deadline, and I was helping. We made the deadline, there was documentation, and they got a POC contract… with a company in Brazil.

In the process of rushing to get ready, we had stripped out all of the plans to make the interface labels link to a file we could localize, and we had hand-coded all the labels. Now instead of handing off a single file to be translated into Portuguese (and having standard labels that could have been done with Google Translate, in a pinch), we either had to branch and hand-code Portuguese labels or spend twice as long digging into the original code and fixing what we had hacked. I’d love to tell you we decided to do it right, but you all know too much about software to believe that happened, don’t you?

The compounded interest from not using a best practice of referred labels when we built the user interface cost us five days of developer time to fix the wrong way, and two weeks to fix and rebuild the right way. That’s a relatively common example of things people skip and pay for later.

Leaving important considerations “until we get a working prototype” means that it’s going to be harder and more expensive to retrofit. Having these fights early prevents you from doing the software equivalent of poking chocolate chips into already-baked cookies.


Next: The Seven Righteous Fights: Localization

If you’d prefer to watch the talk as I delivered it:
Shortest recorded version: At The Lead Developer 2016

Longest recorded version: At SpringOne Platform 2016

What is a documentation architect?

When I was at Write the Docs 2015, several people asked me about the title I have in my LinkedIn heading: Documentation Architect.

What did I mean by that? How is it different than content management or development architecture?

What a documentation architect isn’t

A documentation architect isn’t psychic. They can’t figure out your business needs unless you tell them.

They aren’t necessarily managers. They are designing the documents and process, not the team to build out the documents.

They’re not community managers. That’s a underrated specialty that combines amazing amounts of patience, charm, and detail-orientation. You should have a community manager, but it’s very difficult to combine with document architecture.

It’s not data architecture. The positions seem superficially related, but in this sense, data is the communication software has with itself and other software. Documentation is the communication software has with humans.

What a documentation architect is

Technical writing, like most jobs, is a combination of disciplines in different proportions. I can set up a documentation set, choose a documentation tool, predict usability pitfalls, monitor a translation agency, and conduct user testing.

I also have some less tangible, but equally important skills for building an organization’s first documentation set. I have enough moxie to tell people they are slow in getting their documentation going. I have seen enough successes and failures to have design models for several delivery methods across several industries. I can extrapolate from meetings what is most likely to need documenting in a month, or three, and what we should do about that.

Much like a software architect, I can build something novel, thought-out, and designed to guide less-experienced creators to assemble a product that will succeed over a period of time. Also like a software architect, I need to understand both the business needs of an organization and the skill sets required to accomplish my goal. I’ve come to realize that this form of architecture is about systems thinking and how the pieces come together to form the whole.

The other aspect of my specialty is experience. I don’t just understand technical communications problems intellectually, I have failed and succeeded at almost every type of project you can name. I’ve been doing this for long enough to know the failure modes of so many more projects than newer writers can have had time for. I also have had enough experience in different fields and organizations that I can identify nuances that more settled writers have not been exposed to.

When you are looking for a writer, or a user experience designer, or a developer, ask yourself if you are interested in someone who can learn and grow with your product, perhaps with a little guidance, or whether you are looking for someone who can understand and build aspects of the product in partnership at a higher level. Making that distinction will save you a lot of time both in the hiring process and when you are working with the new hire.

(cross-posted from LinkedIn)