How to Get Programmers to Change User Interfaces

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:

The WordPress interface with all text removed

The WordPress interface with all text removed

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.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

6 thoughts on “How to Get Programmers to Change User Interfaces

  1. Donna

    Sometimes, having them approve your instructions helps them see the non-intuitive design through new eyes: Click here, then here, then here, then here, then here.

    Thanks for that excellent suggestion to improve our credibility by avoiding “I think.” I have found I am up against two barriers:

    1. Software developers tend to think technical writers (ones who don’t have a dev background) are not very bright, along with the rest of humanity.
    2. Double that for the female variety of tech writer.

    Adding “usability” to our discussions helps, I find. If we focus only on features, typical users may never be able to find them. Appeal, perhaps, to their sense of superiority by reminding them that users are not as bright as they are, and may need a more logical design (tongue in cheek here).

  2. Beverley

    Our pubs team faced a similar issue several years ago. Our input on UI text was often ignored. It took a few releases, but over time developers began to see that input from the writers matched feedback from QA and feedback from customers after the product went out. We slowly gained more and more respect and trust from developers.

    When engineering set up a UX team a couple of years ago, we started communicating with the UX reps as well. Because of the relationships we established with developers, QA, and UX, the tech writers on our team are now considered arbiters of UI wording and are asked (and expected) to review all GUI text. In addition, our input on usability issues in the UI are taken seriously.

    So don’t give up hope if you don’t get an immediate result from working with developers on UI issues. Odds are that eventually they’ll see the usefulness of your input!

  3. Mica

    @Donna — Unfortunately, the dev attitude you describe is all too common. Not using “I think” & usability is a good approach.

    I often find that if I can’t write about a feature sufficiently in the context of a workflow, it usually indicates a design/workflow problem. While I’m OK providing work arounds for the user and have done so on numerous basis, obviously “just getting it right” is preferable.

    I’ve always found the need to have concrete evidence when discussing features and usability with developers. Logs of tech support phone calls or direct end-user comments will also help greatly, if you have access to those kinds of things.

    I’ve found that when I’m “winning” (I use that term loosely) these types of conversations with devs, I’ve usually done a few of the following things:

    1. Diagrams. Especially workflow diagrams for the application in question. I have one diagram “the way it is now” and one diagram of “proposed changes”

    2. Thought of common “yeah, but…” answers from the devs and come up with counter points.

    3. Reviewed the devs use case. Keep in mind sometimes it is not the devs fault, as they’ve coded to a use case that is the work of someone else who may or may not understand the full extent of the app. Reviewing the use case can work wonders!

    4. Attend UX/UI meetings regularly. Helps to build credibility for yourself!

  4. Larry Kunz

    Great advice, Tom. And while you didn’t come right out and say it I know you’ll agree that actually making recommendations is the way to go. Not merely criticizing (“This doesn’t work”) or asking questions (“Will the users understand this term?”) but making concrete suggestions that are supported by your knowledge of UX principles and of the audience.

  5. Murdo Guy

    I like the idea of ‘it’s better to be annoying than passive’ a workplace whatever industry it is, this holds true..mentioning your opinions or recommendations on some aspects of the project even though it may not necessarily be a part of your job should always be welcome. this is like looking on the project in a different perspective..anyway, 2 heads are always better than one, right?..just my 2 cents.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>