Get involved in interface design!

by Geoff Hart

Previously published as: Hart, G.J. 2004. Getting involved in interface design. Intercom April:19–20.

It's become something of a truism in the technical writing community that a product feature that's difficult to comprehend and use will be equally difficult to describe. The ideal solution is to fix the problem rather than trying to work around it in the documentation, but to do so, someone has to bring the problem to the attention of the product developers and persuade them to take action. That someone is often us, since we usually encounter the problems long before the product's users.

In this sense, technical writers can act as user advocates by recommending that a problem be fixed, but many of us face a significant barrier to doing so: We must first establish contact with those alien beings in the development department, and even after passing that barrier, we still have to persuade the developers to listen to our advice. That's where user advocacy often breaks down.

Fortunately, it is possible to begin working productively with product developers. It only takes four steps:

Establish a relationship
Offer assistance
Develop and nurture your relationship
Begin influencing product design

Of course, those steps aren't always easy to take. This article should make it a bit easier.

Establish a relationship

I've written many times that the easiest way to work productively with someone is to convince them to treat you as another human being rather than an anonymous name at the top of e-mail or a ghostly voice in phonemail. To erase this distance, you have to let the other person know you really exist. Once a developer begins to see you as a person, you're well on your way to being able to work with them. This seems obvious, but you'd be surprised how many writers never make it this far. Even when there are no formal barriers to making contact, writers and editors tend to be a solitary breed, and happiest when we can hide in our offices and wrestle words into submission. Breaking out of what I call "the cubicle syndrome" takes considerable effort, but amply repays that effort.

Sometimes you can get yourself invited to become part of the development team, in which case you've got a head start on establishing a relationship with your colleagues. Other times, toxic corporate cultures or harried managers raise an invisible but highly effective wall between departments. In either case, you can still establish a professional, mutually respectful relationship, even if that relationship must be informal.

One good way to gain the necessary respect is to demonstrate that you understand their work, since most people are happy to talk at great length to someone who demonstrates an interest in what they're doing. That kind of conversation can easily move from a one-way lecture on the developer's favorite things into a dialogue, and once the dialogue starts, you can begin mentioning your own areas of interest and demonstrating your own competence. Don't start recommending changes at this point, since the goal is simply to demonstrate that you're someone whose opinion is worth hearing.

For example, a little knowledge of programming can break the ice when you're working with computer programmers. Build on that knowledge by developing some expertise in interface design, which you can casually introduce into the conversation. (I highly recommend the works of Alan Cooper and Jeff Raskin.) If your colleagues mostly design more tangible products ("hardware"), have a look at the work of Donald Norman.

Offer assistance

It's human nature to like someone who helps you and resent someone who adds to your burden. That being the case, a great way to break down walls is to offer your help implementing solutions rather than just standing back and criticizing. (Criticism can indeed be constructive and very useful, but no one enjoys being criticized.) Start with "baby steps"—doing things for the developers with little or no payback for yourself. Once the developers begin to appreciate these efforts and trust you, you can start working on things that require more trust, such as suggesting changes to a product.

One good start involves focusing on work that's clearly appropriate for "just a writer". For example, many programmers use "language" or "resource" files to hold the text that will appear in the user interface. Rather than submitting handwritten error reports in the form of annotated screenshots, why not fix the typos directly in these language files? You'll need to learn how these files are formatted so you don't damage the formatting, and you must pay close attention to detail, but they'll appreciate your efforts. I do this work for my own pet programmers, and because our software is released in English and French, I also compare the two sets of text to detect mistranslations or mismatches. Using Word's revision tracking lets me work quickly and lets the programmers review and accept my revisions without any retyping. Plus, they look better when their efforts are reviewed during the quality assurance process. Best of all, discussing any problems I detect starts a dialogue.

Building on this initial success, I offered to help fit text into tight spaces on the screen where they were obviously having trouble describing a field. They already knew their solutions weren't satisfying—even to them—and were grateful for my help. Editing the overly long text for size also let me propose interface changes (e.g., adding headings and subheadings) that further reduced the space occupied by labels, resulting in a cleaner interface. Once, I even used my antequated knowledge of programming to suggest a simpler interface that conveniently made it easier for them to maintain the software.

Documenting an entire product also has advantages, particularly when each member of a development team is responsible for their separate parts of the software. In this approach, each may gradually lose touch with the rest of the product, particularly as deadlines approach and everyone's focus narrows. Understanding the whole product often lets us suggest solutions to a problem one programmer has encountered that another has already solved. Pointing out the solution lets a developer reuse proven existing code rather than having to develop a solution from scratch. A nice side benefit for our audience is that the overall product interface becomes more consistent.

Develop and nurture your relationship

As your relationship with the developers improves, offer to take on additional responsibilities. For example, many developers hate to work on the functional specifications document that defines the team's design targets. Others hate taking the minutes at planning meetings. Filling either role takes them away from the actual development work that they prefer, so offers of help are often eagerly accepted. Though many writers consider this type of work "beneath them", consider the advantages: Apart from any good will you create, you'll also remain far more up to date on the product design than might otherwise be the case. Of course, not all development teams are sufficiently disciplined to create specifications documents or hold regular meetings, but where they do, try offering to help.

You can also score points by paying attention to problems while a product's still undergoing development. You'll generally be working on versions that have not yet undergone final quality-assurance review, so you'll spot bugs and other problems before anyone else. Report these problems to the developers in such a way that you're seen to be helping them produce a more robust product rather than implicitly accusing them of shoddy work. Carefully record all the conditions and steps taken that led to the problem, and confirm that the problem is repeatable. This lets the developers follow your steps and repeat the problem, thereby gaining strong clues to where the problem lies and how to solve it. The product will pass the quality-assurance review with fewer problems, the developers will look good, and you'll find yourself a true part of the team.

Jokes notwithstanding, product developers are people too, and appreciate being treated as such. Relationships must be maintained and strengthened to get you through the occasional crises that arise on the job—such as a sudden change in the release schedule that throws everyone into a panic. Staying in friendly contact with the developers, particularly when you aren't asking them for favors, prevents you from being seen as the kind of person who only comes around to raise problems and take them away from their work. After all, a good relationship must be about more than "I need something from you".

As I've already noted, it's easiest to strengthen an existing relationship if you make someone's life easier rather than simply creating work for them. If you can prove over time that your advice is useful, that you're willing to spend time with the developer as a person (not just as a developer), and that you're willing to treat the developers as equals, you'll gradually strengthen your relationships to the point that people will come to you for advice without being asked. Better still, you'll be able to go to them with unsolicited advice, confident that you'll at least get a fair hearing.

Begin influencing product design

Watch for useful verbal clues. "We've always done it that way" is a good sign that someone doesn't understand why something is being done and gives you a chance to ask "why?" Of course, rephrase that question more diplomatically in a manner that doesn't challenge the person: "What objective are you trying to achieve? Are you satisfied that you're achieving that objective? No? Want some help brainstorming a different solution?"

Developers grow frustrated when their initial designs are repeatedly rejected by managers, the quality-assurance staff, or other critics. If you demonstrate that you can propose workable solutions, it won't be long before developers learn that working with you early will reduce the number of times they must redesign an interface. You may even reach the point where they work with you to design a near-final interface before they actually begin work on the actual product—the holy grail of working with developers.

Pointing out problems is all very well, but make sure you can offer solutions that would solve the problem—or at least offer a few options and indicate your willingness to come up with a compromise solution. Don't be seen solely as a constant critic of someone's design efforts; instead, become their collaborator. Discuss changes rather than trying to impose them, and brainstorm solutions rather than clinging desperately to your own ideas. These strategies increase the other person's willingness to listen and decrease the risk of them growing defensive.

Recognize that an ideal solution not only solves the problem but is also easy to implement. Sometimes time constraints and other pressures mean that you must accept a partial or temporary solution rather than holding out for a "perfect" solution that would demand more time than the developer has available. Those perfect solutions are worth recording for future action so that developers can implement them in a subsequent release.

Try, try again

There's no guarantee of success, even if you make your sales pitch clearly and convincingly, and that's particularly true if your developers are at their wits' end trying to meet insane release schedules. In that case, all you can do is try to demonstrate how working with you saves them more time than it costs them. Once they understand that, self-interest will encourage them to seek you out.

It bears repeating that developers really are human, and in the rush to meet deadlines, will occasionally forget to include you in their plans. For example, I recently updated an old help file before a software release by working from a clearly itemized list of changes provided by the lead programmer. But in reviewing these changes, I discovered many interface updates that had been implemented over the past year without notifying me. That meant I'd have to compare the documentation line by line against the current interface to avoid any embarrassments.