The Technical Writer as an Outsider: How Ambitious Are You? [Organizing Content #22]

by Tom Johnson on Aug 6, 2010
categories: findability • technical-writing

After our recent reorg, our tech writing group, now split up, has been wondering about the best way to realign ourselves in the new reporting structure, which has yet to be fully defined. Will we end up at the bottom, relegated into some lonely, forgotten corner of the org chart? Will we be grouped with the finance accountants and the secretaries? Or clumped into some other miscellaneous grouping, like a collection of odd socks?

My colleague Gryphonmountain and I decided to act aggressively to ensure we weren't forgotten. We wanted to maintain some visibility in the new reorg so that we would have leverage to insert ourselves into projects early, so that we would have some connection with project managers before they solidified their project plans and budget.

The Meeting

We met with a lead interaction designer (involved in the restructuring) who could advocate for us. We decided that he could be our voice. As we talked about where and how we might fit into the new structure, he said, I have to be frank, I haven't been very satisfied with my experience of help. Where you fit in the redesign depends on how ambitious you are. Where do you want to be?

As we talked, he expressed several commonly held beliefs by interaction designers. The holy grail of interface design is to not need help, he explained. Users who search through help material outside of the application often do so as a last resort. Unless help is integrated directly into the user interface, it rarely gets used.

He clearly preferred to include help inside the user interface in an integrated way. Help shouldn't be something separate from the application, he suggested. It's built into the application, seamlessly woven into every window and screen that needs it.

The interaction designer mentioned the possibility of blending our role with usability, and asked where we saw ourselves. Technical writers don't need to limit themselves in merely writing documentation outside the application, nor even integrating the help content into the interface, he explained. We could play roles in crafting the language of the interface, in coming up terminology and button names. We could take one step further and participate in usability, helping define the task flow and organization.

It all depends on what you want to do, he said. You create opportunities for yourselves. But like everyone else, if you want a seat at the table, you have to prove your worth.

He was bold and forward thinking. But was help outside the application useless? It may be possible to bring in tips and short paragraphs of instruction within the interface of a simple web app, I thought, but anything complex would need an external help file. You can't learn Photoshop by reading little pop-up tips, right?

If help is moved into the interface, where's the best place to show it? And how much help material can you add? Can you include videos in the interface? A tour?

Certainly limiting yourself to snippets of text here and there, pop-ups, expanding sections, and maybe even short side panes that appear or disappear at the user's command isn't possible unless you work closely with the interaction designer throughout the entire design process. It's not something you can just add in a the end. You have to think carefully through each screen, be familiar with your users' pain points and question areas. You have to conduct actual usability testing to identify problem screens.

Integrating so closely into the design would require our involvement early on in the project, he explained. That's why I asked what you want to do. On the other hand, if you feel content providing external help only, you could be brought in much later.

What we wanted -- our level of ambition -- would determine our place in the new department organization.

An Advocate Whose Idealism Excludes Us

Despite the interaction designer's dismissal of the value of help outside the interface, and his biased definition of ambition, I felt a sense of awe for his grasp and view of our potential. He didn't see us as mere writers, but rather as intelligent project members capable of providing input in usability, business analysis, interaction design, and other customer-oriented aspects of the project. I'm not sure that a reorg can address the level of integration he envisioned with tech writers and the software development process, but he gave me a lot to think about.

Later, as I was talking with my manager about the holy grail comment (the idea that a perfect design doesn't need help), my manager wondered about the value of having someone advocate for us whose idealism by definition excluded our role. The more I thought about it, I felt my manager was right. Although it often seems interaction designers and technical writers are cousins aligned toward the same goal -- user advocacy -- in reality we approach our jobs from different philosophies. We may not be as compatible as we usually think we are.

Interaction designers interpret the need for help material as a failure with the design. Their ideal project is to build an interface so intuitive that you don't need help material. Every text pop-up you add, every snippet of help text in the interface, every question mark that expands with more information, is an admission of shortcoming in the design. Our mere presence is a crutch signaling the designer's incompetence.

In contrast, technical writers see the value of complete information about a product. We've had too many experiences with poor or missing documentation. We've been frustrated at the absence of information, and we want to provide users with the full story. It's not a story you can tell in a few sentences here and there in application pop-ups. And we scoff at every designer or program manager who uses the word "intuitive." Intuitive to whom? Maybe to the person who designed or built the application, but definitely not to the user, who approaches the application for the first time.

The Value of an Outsider

I often hear frustrations from technical writers who are brought in at the last minute, with little time to prepare help materials, with no input on the interface because it is now frozen. They don't have any rapport or trust built up with the project team, so they are almost strangers.

It's a situation and complaint I am all too familiar with. Ever since the reorg, I have been ranting about this predicament in a jaded way. We need to be involved early on. We are more than just documentation writers. We can contribute towards usability and design. We can improve the clarity of the interface. Just like the direction the interaction designer wanted us to move, we can be inserted early and wield a more significant project voice.

But there's also another ideal, perhaps equally romantic. It's the idea of the technical writer as an outsider. The project team is on the verge of release. They have just one more box to check off -- the help. They finally make their way to the end of the cube row, to the farthest edge, where the technical writer sits patiently and quietly. They give him a URL and access to the application.

The technical writer works quietly and quickly. He makes phone calls, talks to users. His outsider perspective serves him well, as he is not inured to the workflow and concepts in the application. He hasn't been with the application so long that he can no longer see the areas of confusion. To the team, the concepts that were once new and maybe odd are now so common and familiar that they are blind. But the technical writer is an outsider, and by being an outsider, he can see what the project team cannot.

As he writes, the project team is surprised at the simplicity. Why is he writing that? they ask. We didn't think that needed help, they say. Why isn't he using that term, they wonder. Why is he asking so many questions? Why isn't everything in the app so plain and simple? Why is he making video tutorials about that screen? Why is he telling us that we must change the language here? The help material is so much longer than we thought it would be. Why do we need so many examples and illustrations?

What you can write as an outsider is often more helpful than what you can write as an insider. While I respect the efforts of technical writers to insert themselves into projects early on in the process, to wear multiple hats, logging bugs, expressing opinions about designs, acting as the voice of the user during moments of early project decisions, there is a weakness that comes about from being an insider. It's the curse of knowledge -- the more you know about a project, the less able you are to articulate that knowledge, because you know too much. Your own knowledge cripples you. You bring in too many details, you fail to see the interface through fresh eyes. You omit location phrases and other screenshots because you've been staring at the interface for months, so you know where everything is -- and it all seems intuitive. As an insider, you've become just as blind and dumb to the application as everyone else. What seems odd to the users doesn't seem strange to you at all, as an insider.

Every software project needs an outsider, an audit. They need a check point that kicks them in the rear before they release the project. The technical writer as an outsider can provide this perspective. It's a lonely task. You may be hated and treated like an orphan at the back door. Designers may scoff at you. Project managers may ask why you need so much text. There may not even be budget for you, but bill it. Bring down the ax against intuition and obviousness. You are the first user. By being an outsider, you have incredible power. It's a power that insiders can never access.

-----------

photo by Paul (dex)

Next: 3.3 The Interface Is Text [Organizing Content #23]