Technical writing and interaction design

Technical writers are oft-forgotten constituents in the product development cycle. Although they are rarely tasked with participating in product requirements definition and product design, technical writers are in a unique position to affect product design. However, they will find that subtlety and subterfuge are sometimes necessary to make a politically correct impact in an organization that has not embraced interaction design as a formal part of the development process.

Technical writers and interaction design

When I started my career as a technical writer in 1992, interaction design did not exist as a stand-alone discipline in a product development organization. My role in the development process went something like this: early in the development process, I made a documentation-effort time estimate based on some vague, high-level requirements provided by a product manager. Months later, development would finally distribute an early internal release, which only faintly resembled the initial requirements definition. The technical publications team would revise our time estimates and scramble to start documenting the software. Once a week, the development team would release another internal version of the software—which might or might not resemble last week’s release—and so on.

As a technical writer, I felt this process offered a unique opportunity. I was one of the first non-developers to get my hands on the product. Because it was my job to be the liaison between the software and the user, I had to think critically about the software from the user’s perspective. I always enjoyed the challenge of documenting complex interactions. It was rewarding to create a coherent narrative of text, diagrams, screenshots, and callouts to describe an otherwise incoherent interaction. Soon, though, I realized I was missing an opportunity: wouldn’t it be better to improve the interaction instead of spending time creating a documentation band-aid to cover it up?

History repeats itself

My first attempts to insinuate myself into the product development process weren’t exactly successful. In one instance fairly late in the iteration cycle for a developer’s workbench, I noticed a yellow triangle in a prominent position on the toolbar. There had never been a yellow triangle there before, and it certainly wasn’t mentioned in any of the requirements sheets that I had seen. Clicking on it didn’t seem to do anything, so that was no help. I asked other tech writers, the product manager, and some developers, but nobody knew what the yellow triangle did. Finally, I tracked down the developer responsible for the yellow triangle.

"So, what’s the yellow triangle for?" I asked, pen poised above my notebook.

"Ah. It’s a history button," ("of course" was strongly implied in the response).

"But nothing happens when I click on it."

"That’s because you haven’t done anything yet to write to the history buffer."

I decided not to ask, "Then why can I click on it if there’s nothing there?" and tried a new tack.

"Okay, why exactly is it a yellow triangle?"

Not only did the developer have no response to this question, he became frustrated with me for questioning him about product decisions that had already been made. He had so much work left to do because of shifting requirements that the last thing he wanted was to revisit completed work.

As I gained more experience, I learned some strategies for getting rid of some of the yellow triangles that invariably crept up in every product. I wasn’t an interaction designer by trade, but I was performing some of those responsibilities, albeit in an undercover mode. Who would suspect a mild-mannered technical writer of participating in the product definition and design process? Below are some strategies that you can use as a technical writer to make your products better without stepping on too many toes along the way.

Be a champion for the user

You may need to make a mental shift about your role as a technical writer. As the first people actually trying to explain how the product works in users’ terms, technical writers are in a unique position to spot problems. It is your responsibility to bring to the attention of the appropriate people—in a delightful way, of course—shortfalls in the product before it hits the marketplace. Certainly many of these problems might not be fixable in this release, but at least you have alerted the people in charge of schedules and deployment dates so they can make informed decisions about how to proceed.

Insinuate yourself in the design process

Of course, noticing problems during the internal release iteration cycle is late in the game, and making more than minor changes to the product has major scheduling implications. Better would be designing the product with more clarity early in the process. But without dedicated design resources, how?

In the absence of having a dedicated design team, sometimes simply increasing awareness in your organization about making time for design and for defining clear and stable requirements up-front makes a great impact.

Does the following sound familiar? Marketing specifies vague, high-level requirements in a bullet list, but the spirit behind the list remains undocumented. Development then attempts to create a product from the list, but lacks the context and details necessary to make clear decisions. When marketing sees the product later, there is a disconnect, and the everyone has to twist and pull the product to try to achieve the original product vision.

So where can a downtrodden technical writer fit in? By simply doing what you’re best at: using clear writing to articulate ideas, being organized, and following through on details.

Get yourself invited to requirements definition meetings

Volunteer to take notes and document them for the team. This will keep you in the product-definition loop. Not only will you have a chance to discover areas of the product that are not defined in enough detail, you will get a jump on assessing your documentation writing needs, instead of finding out at the last minute. Be careful not to take over the meeting, or even to participate much at first until your colleagues are used to your being there. You’ll have a chance to be heard within the text you write in the meeting notes, where you can stealthily point out areas of the product definition that are thinner than others.

Keeping ownership of requirements definition meeting notes also keeps the rest of the development team honest about changes made later in the process. Developers (and tech writers) can use the document as ammunition for requesting timeline extensions, since new features weren’t accounted for in the initial time estimates. It also decreases the likelihood that an individual will be able to get a pet feature added to the product ad hoc.

Create relationships and forge alliances with product developers and marketing stakeholders

Developers are used to getting burned by shifting requirements late in the development process, and may be wary of a random technical writer discussing interaction design with them. Go meet the developers early in the development cycle. Share with them experiences in the past when maybe you too got burned by shifting product requirements, and help them understand that you want to help avoid the same thing happening on this project. In return, you’ll get the inside scoop on what’s actually being developed, and maybe notice red flags about where important areas of the product are not getting enough attention as developers race to meet deadlines. As the first person responsible for describing the product to users, you will be better able to prioritize what is really important to users. Share this information with the product team, and assess where the product fails to meet fundamental user needs.

I’ve found that the best way to earn the trust of a developer is to ask a lot of questions. Don’t try to impress them with answers to how the product should be developed. By asking intelligent questions, you’ll create an atmosphere of collegial dialogue, rather than coming across as yet another "expert" there to tell the developer what to do.

Likewise, spend some time with appropriate marketing stakeholders involved with the product. Often, technical writers are part of the research and development side of the company organization chart, and their only contact with marketing may be via the product manager. However, understanding the marketing perspective is important, too.

The best way to do this is to schedule one-on-one meetings with the appropriate marketing and development stakeholders in your project. Forging these relationships will give you credibility and familiarity. This allows you to voice an opinion about product requirements early in the process. From a tactical perspective, you’ll learn important information about what needs to go in your user documentation, in details that wouldn’t otherwise show up in a feature sheet.

Document bad interactions

Spend time documenting egregious product interactions and share them with appropriate developers and marketing people. If it takes you several pages of text, diagrams, and decision trees to describe what should be a simple or commonplace interaction, this is a great indication that the product interaction is flawed. Share the documentation with others on the product team and let them see the complexity. Sure, you can "write around" bad interactions, but that doesn’t mean that users will be satisfied (or even be able to complete the interaction). This is especially effective for a common user task that requires multiple individual interactions. Product specifications typically isolate each interaction, and by themselves none of them may look complex or laborious. Documenting the complete task from a typical user’s perspective mimics what users will actually need to do.

Create personas

Personas are user models that are based on research primarily consisting of interviewing and observing users. Personas are powerful and effective tools for clarifying product requirements and preventing feature-creep. They are also useful tools for technical writers as they plan, prioritize, and write user documentation.

Creating personas is not a trivial task, and deserves its own discussion. For other newsletters about personas, see:

http://www.cooper.com/insights/journal_of_design/articles/personas/

In conclusion

Being a stealth user advocate doesn’t mean that you have to draw screen sketches and spend nights designing detailed product interactions. Rather, it means that you use your position as a champion for the user to raise awareness about user needs and egregious product interactions as early in the development process as possible. To do so, you’ll need to work hard to create an environment in which the appropriate people on your product team listen to you. Not only will your technical writing job be more satisfying (and perhaps less chaotic), it will lead to better products for your customers.

1 Comment

Virginia Lynch
This is a great article that offers concrete suggestions on how to overcome this major obstacle for technical writers. Please keep me posted about additional work you may have done on this subject. I have a group in LinkedIn called 'Tekwriting.net' where we have discussions about these topics. I added a link to this article today from my group. Please feel free to connect with me in LinkedIn and join this group.

Post a comment

We’re trying to advance the conversation, and we trust that you will, too. We’d rather not moderate, but we will remove any comments that are blatantly inflammatory or inappropriate. Let it fly, but keep it clean. Thanks.

Post this comment