Why Tech Communicators Find Problems That Others Miss

there is such a thing as a bad cupcake (apparently)

Creative Commons License photo credit: katiemarinascott

Do you ever feel that you’re doing as much Product Management as you do writing?

I’m building an online portfolio, so I’ve gone through a lot of my old documents to get some samples, and I’ve notice something interesting.

The docs I deliver, which are supposed to contain things like Interface text or Help text, also contain tons of suggestions to change features, flows, buttons, and screens. And not change a little. Several times, I’ve suggested that we remove (or add) whole screens, or even sets of screens from an interface.

And to cut to the chase, almost every time it was technically feasible to make the change I suggested, the team agreed to do so. In other words, I was catching issues that needed work.

My point is not that I’m really good. My point is that most tech writers would have found the same problems. Writers seem to catch issues with flow, design, or feature sets that would otherwise go unnoticed by the team.

Why is this?

The question could mean at least two things:

  1. Why do tech writers catch problems that other people miss?
  2. Why do tech writers catch problems that have nothing to do with writing?

I have some theories about the first question, but I’ll stick to the second one for now.

Why do tech writers catch problems that have nothing to do with writing?

Actually, it’s kind of a trick question, because everything we write about has to do with writing!

If I’m writing about how to move from screen to screen in an Installation Wizard, then moving through those screens is my business. The flow in question DOES have to do with writing.

Ok, Smartypants: Why do tech writers catch problems with flow, UI, and features?

I’ll tell you this much: It’s not because we’re smarter than the rest of the team. I’ve worked with really brilliant Information Architects, Designers, Developers, and Product Managers, but I still find “gotchas” in the UI. Something else is going on.

I think we get tipped off about problems when our jobs are harder than they should be.

Because really, we’re pros, and we know how to guide someone through a flow. We know how to explain what a given button does and when a person might want to click it.

So when I find myself really struggling to explain what’s going on, I start to wonder what the problem is. And after wrestling a while with the words, I scrutinize the thing I’m writing about.

“Hmmm,” I say, “if this button wasn’t here, or if it did something slightly different, the page would be easier for me to write about.”

“Hmmm,” I say again, “if this screen took people THERE instead of HERE, then I could reduce my word count by half.”


And you know what? I’ve found a golden rule of tech comm:

A change that makes a thing easier to document is a change that makes it easier to USE.

When, purely to make my job easier, I imagine the UI without that pesky button, I find that a person using the software has one less obstacle. If that tricky screen went to a different place, my audience would accomplish its goal in three steps rather than five.

And that’s when I send my note to Product Management.

Has anyone else found difficult writing to equal problems in the UI? Do you find that you frequently suggest changes outside the realm of the words?

Tags: ,

5 Responses to “Why Tech Communicators Find Problems That Others Miss”

  1. September 29, 2010 at 9:14 am #

    I like that correlation: easier to document equals easier to use.

    You said that we know how to guide someone through a flow. That’s true, but it’s even more than that. We’re much more likely than the developers to think the way a user thinks, to see things from the user’s point of view. If it looks hard to us, then it’ll probably look hard to the users too.

    • September 29, 2010 at 9:21 am #

      I completely agree, Larry.

      And of course, it’s not just developers. There are also (often) IAs, Product Managers, and others who have looked at it.

      I think we’re the first ones to basically pretend that we’re using the thing in order to do our jobs.

      (And I think that this is especially true when we write task-based help.)

  2. September 30, 2010 at 3:01 pm #

    You’ve given voice to something I’d like our project teams to understand—this is why they need us throughout the project lifecycle to analyze designs rather than to come in at the end and just write some docs. If it’s hard to explain, it’s hard to do.

    If anyone ever asks me to prove it, I’ll point to this post.

  3. October 4, 2010 at 12:49 pm #

    I am in the hybrid role of having to document the new feature, then provide training training for it. Since it’s our job as writers to turn function into business process, we have to understand the user’s business process. Developers rarely have that perspective.

    I push back so much on our development team that now they often consult with me during the design process. Then both our jobs are easier when they throw it over the fence.

  4. January 24, 2011 at 1:53 pm #

    Agreed – writing user assistance makes us look at the product through our customers’ eyes, and usually we’re the first ones to do that. What makes sense in the code sometimes makes “HUH??” in the UI, and often it’s not officially anybody’s job to catch that. We do it anyway, and we should track it better – it’s a way we add value, but most of us wouldn’t be able to prove it at review time.

Leave a Reply