How to Get Programmers to Change User Interfaces

by Tom Johnson on Jan 26, 2013
categories: technical-writing

I received the following question from a reader:

Hi Tom,

I absolutely love your column and feel as though you are writing for me. I was wondering if you could devote an article, or maybe you already have, about how to approach programmers about their screen designs.

Our company has three totally separate divisions that focus on different things. I've just been moved to a different division, and I've found the programmers in this division aren't as up-to-date with their styling of screens.

Currently, we don't have a design team, and its totally up to the programmers as to how to design screens. I could see areas that could make the screens (is the term “screen” outdated?) much more user friendly if the programmer would only tweak a few things and offer different buttons.

Should a technical writer offer such suggestions, and if so, how would you go about doing it gently so as not to hurt feelings? I'd love to read your insights on this matter.

Thanks for contacting me with this question. Most technical writers, in documenting how applications work, have suggestions for improving the interface. After all, few people are more intimately familiar with an application than a technical writer who creates documentation for it. Whether the application was designed by an interaction designer or developer, there are usually gaps that weren't anticipated, workflows that weren't entirely thought through, and words and phrases that could have been better chosen.

As a technical writer, first assume that you're the expert about text in the interface. An interaction designer may know all about attractive colors and layout but not really know the right words to use. Similarly, developers probably struggle with word choice. Your first suggestions might be about improving the names of buttons, error messages, interface text, and so on. You're the wordsmith, so project members are looking at you for direction here. Don't be shy.

If you feel like you're encroaching on others' territory, try this exercise. Remove all the words from your interface and see what's left. For example, take a look at the following screenshot:

Can you see how integral language is to an interface? This is the tech writer's domain, not just the space of interaction designers and developers. (For more details, see my post, The Interface Is Text.)

Other Suggestions

Beyond interface text, if you have suggestions for improving the design, layout, workflow, or functionality, definitely voice them. You will be seen as a much more integral player on the team if you contribute your feedback about the design.

Overall, don't draw lines around your role as a technical writer and  limit yourself to documentation only. More and more software departments are following agile methodologies. In agile, project team members wear multiple hats and play various roles. The lines about who does what are more fuzzy.

Ways to be Tactful

As for the most tactful way to make your suggestions, if you have a design review meeting for your team (when people sit and discuss the improvements they're going to focus on for the next release), it's a great time to give your recommendations.

If you want to add weight to your recommendations, don't just say "I think." Instead, say "The feedback were getting from users about X is ...." Or "Many users are getting confused in the application here." The more you can connect your recommendations with user feedback, the more your project team will believe you.

You will also soon be seen as one who champions the user's voice. The project team will look for your guidance because you help identify user concerns and relay them to project teams. Connecting user feedback to project teams is a key role that technical writers can play — and one that project teams value highly.

Annoying Is Better Than Passive

Sometimes you may need to be a little annoying to get your point across. That's okay. At my last job, we had a lot of volunteers who wanted to help out. I started working with a senior gentleman whose background included nearly 40 years as an engineer at Unisys.

As a volunteer, he monitored forum threads, incoming feedback, and other activity for a specific product. He relayed important feedback, broken functionality, and other issues that needed to be addressed. He filtered out the noise and escalated the real problems.

When he first started, the project team found him a bit annoying, because he would go to their cubes and ask questions like, Why did we release this application with broken functionality? Why didn't we roll it back when we realized there was a major glitch? Why can't this user see what they're supposed to be seeing? etc.

But the team quickly learned how valuable his feedback was. Soon the lead QA engineer on the team asked if we could have five more of these volunteers, each assigned to various products. He said it's better to have someone be more aggressive and annoying than passive and quiet.

Keep that story in mind. Developers and designers may initially be defensive and try to dismiss your feedback. But soon they will get past their defensiveness and learn to value your feedback, especially as it represents the user's point of view.