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

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.

Your perspective as an outsider is unique and powerful.

Your perspective as an outsider is unique and powerful.


photo by Paul (dex)

Adobe RobohelpMadcap Flare

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.

  • John Hewitt

    Nice Article. I have had the same struggles within organizations. My role has changed so often that I have a hard time defining it myself at times. I’ve had moments when my input was valued from the beginning, but for the most part I end up coming into the process late, hoping to make my real fixes when the 2.0 product comes out. It is a challenge.

    • Tom Johnson

      Thanks for being the first to comment on this post, John! I think that after going through about a dozen reorgs, one must become somewhat desensitized to the structure in place. What have you done in past reorgs to reassert the position you want?

    • John Hewitt

      To be honest, when a company makes a point of constantly reorganizing, it can be hard to decide how active a role you should take. You hate to commit to the new regime when, in the back of your mind, you know that another reorganization will come sooner or later and you may have picked the wrong team. I just try to maintain the relationships i do have, because those are generally the people i trust and know I can work with.

  • Anne Sandstrom

    I empathize with much in this post, except for one crucial point. A good technical writer can always put themselves back in the position of being outside the “development bubble.”

    It’s always better, from the user’s perspective, to have a more usable product that needs less documentation. Even if an organization doesn’t do usability testing, the tech writers are the first line of usability. I often refer to myself as User #1. As we all know, if it’s hard to write about, it’s hard to use. The more “set in concrete’ the design is, the less likely it will ever be improved. Ultimately, it’s an expensive proposition for an organization.

    • Tom Johnson

      I agree that it’s better to have a more usable product that needs less documentation, but if the tech writer is incorporated into usability and becomes an insider, you might end up with a more usable product with worse documentation. In my case, we already have interaction designers who perform a usability role, so doubling the tech writer into usability creates overlap. Sure two usability people are better than one, but it’s hard to make this case to project managers with limited resources.

      You said that a good tech writer can “always put themselves back into the position of being outside the ‘development bubble.'” To a certain extent, our ignorance about the code prevents us from being trapped into certain assumptions about the way the application works (at least for me). So I’m always outside the developer’s mindset/bubble to some extent. But I’m not sure what reason you have to believe that a tech writer is somehow above the curse of knowledge. Once you know something well, it’s hard to see it from the perspective of not knowing it. This is one of the paradoxes of tech writing. You have to know a product extremely well to document it, but the better you get to know it, the more challenging it becomes to organize and present that knowledge in a way that satisfies the outsider’s perspective.

  • Jason

    This may be one of the first times I find myself really disagreeing one of your posts. I think Anne captured my main disagreement well with her comment that, “A good technical writer can always put themselves back in the position of being outside the ‘development bubble.'”

    I was lucky to be involved early in the development process for the better part of my tenure at my current company. I contributed to onscreen text and embedded user assistance in the application, as well as external Help and printable materials.

    If you have the opportunity to be involved in the development process early on as a tech writer, I think you should jump at that chance. I think you’ll still be able to maintain that outsider’s perspective, despite your closeness to the project. Plus, with early involvement, you can help catch some of the end user trip-points before they make it into the final product. This often means that you can spend time documenting things like best practices for using the product, instead of documenting troubleshooting tips to get around a clunky feature.

    Having the opportunity to get involved early in development can also mean a chance to expand your intellectual horizons. Development began trusting the writers here enough to let them get directly into the code to edit onscreen text, error messages, and so on. It helped me learn more about programming, which, in turn, helped me to better communicate with developers in their terms. All of this combined greatly improved the perception of the tech writing role and its importance to the cross-functional team.

    Sometimes I think tech writers embrace the stereotype of the tech writer as an outsider for nothing else than to continue to have a reason to lament or commiserate with their writing peers.

    • Tom Johnson

      Jason, you make some good points, and I may be entirely wrong about the outsider argument I make in this post. I’ve had both kinds of roles on projects — sometimes as an insider from the beginning, other times as an outsider near the end. I admit that being an insider is more fun, because you’re part of a team. In this post I was trying to explore an alternate point of view. What happens when you are an outsider? Maybe things aren’t so bad — maybe you have an advantage that insiders do not. Is that mentality a delusion to bring comfort to a poor situation? Wow, reminds me of Nietzsche there. Maybe.

      As for the ability to play both insider and outsider roles, I’m not sure if I completely agree with you and Anne. Once you’re an insider, it’s very hard to erase that knowledge from your brain and see things anew without simply observing users who are new to the application. I think you overestimate our ability to move inside and outside of a knowledge domain. Once you know how to do something, it’s very hard to forget that knowledge and write as an outsider.

  • Karen

    I agree completely. Tech writers bring an objectivity to an application that users need. This brings up a favorite pet peeve: Writers who kvetch about not being treated as equals to the developers, who complain when developers don’t return comments immediately, who are indignant when project managers pay more attention to the developers than the writers themselves. We’re in a service role. It’s not that we’re less important to the developers; it’s just that we’re dependent on them to produce something we can document. Your post states simply what I’m trying to say: We’re different. And that’s what the users need us to be.

  • Techquestioner

    If the tech writer isn’t the only writer in the organization and isn’t assigned only to that single software project, I think most competent tech writers can review and edit the interface for a product early in development, and come back to it later with an outsider’s perspective to write help or a manual from the user’s viewpoint. Juggling several projects is much more typical, and switching between disparate projects can give you “fresh eyes” when you return to it in a later development stage.

    • Tom Johnson

      Thanks Techquestioner. The juggling of projects and fresh eyes comment was insightful and probably true of most of our experiences. I appreciate your joining in on the conversation.

  • Larry Kunz

    This lead interaction designer sounds like a fascinating person. You went to him with a need, and he managed to change the subject and dismiss you. Dismissed you with a pat on the head and got you to say thank you on the way out the door. Your manager was right: this isn’t the guy you want for an advocate.

    If you position yourself as an outsider, you’ll be an outsider. That entails a good bit of risk. The developers might listen politely, but they might not return your phone calls and they probably won’t care what you have to say when a deadline is looming.

    I agree with Anne: it’s better to be an insider, but not so far inside that you can’t step back and take the outsider’s point of view. It’s not that we know less than the development team (as would be the case for an outsider). It’s that we know more: we know the audience and their mindset.

    • Tom Johnson

      I think everyone agrees with your assertion that it’s better to be an insider than an outsider, even in spite of my attempt to argue the value of the outsider’s perspective. Most of the commenters also feel that they can simply put on the outsider’s hat whenever they need to. If that’s the case, maybe I should focus my attention on techniques for seeing the outsider’s perspective. Many of the fiction writer types are accustomed to stepping into other people’s skin. Hmmm, I will have to think about this for another post.

  • Janet Swisher

    Lots of food for thought in this post, Tom. I have two thoughts in response:

    First, I agree with your interaction designer that user assistance is an aspect of user experience. But I disagree with the notion that each scrap of help is a failure of design. Is each bug found by QA a failure of development? Is each support call a failure of documentation? He needs to expand his view of user experience to include everything that enables the user to successfully complete their goal, which includes information (documentation) that provides a conceptual framework, and guides them along the way.

    Second, I think you’re conflating “being an outsider” with “coming in at the end”. I agree with other posters that it’s possible to adopt a critical stance toward the product while still being involved early in the project. That’s what QA does, though in a different way. They manage to avoid using the product in the way they’re “supposed” to, even when intimately familiar with it. Likewise, a professional tech writer should view the product “as if” they were a new user, even while knowing it inside and out. Being a new user, and adopting a new user perspective are not the same thing, and tech writers do the latter.

    Certainly, make this interaction designer an ally if he can help you get involved early in projects. But don’t rely solely on him to be your advocate. You need allies all across the organization, but especially anyone else who interacts with users.

    • Tom Johnson

      Janet, your comment is my favorite on this thread.

      Is each bug found by QA a failure of development? Is each support call a failure of documentation?

      I like your point about learning from QA. By using the product in unconventional ways, we probably can see the product more as an outsider. I still think that peeling back the layers of knowledge is harder than most people make it sound here. It’s a delusion to think we can unlearn what we know at the snap of our fingers.

  • Julio Vazquez

    Glad I finally got around to finish reading this. (A few distractions today) I think this is a good post but I do tend to disagree a little with you, Tom. I think tha tthe lead interaction designer threw down a challenge that you should have accepted and then went on to be a chameleon that would meet all needs.

    My thought (and I know I’m sometimes obtuse) is that I should position myself as an insider and an outsider. I should become an insider to engender the trust and respect of the team but an outsider to be an advocate for the customer on multiple levels. It’s important, IMHO, to be there at the beginning so suggestions can be implemented while keeping the expense in control. It’s very true that the later the input, the less possible it becomes to implement in the current release and those recommendations become the bottom of the priority list for the next release. The fix: document it. Really not a benefit to the customer.

    My best story along these lines is becoming enough of an insider that I made recommendations early to the team in a positive manner keeping my customer hat on. As time went on with my relationship with the development team for the product it got to the point that the developers came to me to validate directions they took on customer-facing information.

    That’s what I think is the epitome of my career. They came to me for the answers, I didn’t have to insert myself any more. đŸ˜€

    • Tom Johnson

      Thanks for commenting, Julio. I know the post was long. Glad you could finally get through it. :)

      I like how you compare being an outsider versus an insider. I know I’m definitely running against the general thoughts on this one.

  • Mariann Foster

    My group is currently going through the opposite experience. We are being taken from “outsiders” and thrust into the middle of the development. Since our priority is customer training, we used to develop the training once the product was done. That way we got to see if from the new user’s perspective (and we got to document and find work-arounds for the finished product).

    We are now part of the development cycle. On one hand it has been nice to be able to add to the development and “fix” things that we know would trip up users. The consequence of this is that we are documenting the same thing multiple times and having to change teaching techniques on the fly to keep up with the changes in product.

    We’ve been able to keep the “new user” perspective simply because as a group we are still learning the product. I’m just wondering if the fixes we’ve added to the development have made up for the extra work required to constantly verify and update our material to match the development changes of the product.

    • Tom Johnson

      Hi Mariann, thanks for the comment.

      The consequence of this is that we are documenting the same thing multiple times and having to change teaching techniques on the fly to keep up with the changes in product.

      Very true. This is one argument for coming in at the end of a project to document it — there’s no need to change topics you’ve already written.

      I can’t remember … are you in Utah? I know we’ve met at an STC conference before.

  • Scott

    The last paragraph says it all for me. Technical writers can be that outsider, at all times during a project. And you have to accept that you will 1) sometimes (and more frequently) need to be rather forceful in getting your point across, and 2) you will rub some people the wrong way.

    Of course, it can be frustrating when your comments and suggestions are ignored or discounted. Definitely an occupational hazard.

    • Tom Johnson

      What are your tips on playing the outsider role? How do you imagine that you do not know certain things? Seems easier said than done.

      Re the occupational hazard, definitely. Makes the blood pressure boil to be ignored.

  • Scott

    Tips for playing the outsider? Be yourself, but try to keep your anger and frustration under wraps. As I mentioned, you need to be forceful but not aggressive. It’s hard to do, and no matter how hard you try someone will take something or everything you say the wrong way.

    Of course, the other option is to come into a meeting with an axe handle, lay it in the table in front of you, and say “Folks, there are going to be changes” …

  • Rengaraman

    Another thought provoking (comments too) post from you Tom.

    While being a part of QA team, I feel a Technical Writer need to be an Insider. But when he/she sits for documenting, better to think and document in customers’ point of view.

  • Harry

    Sounds like the interaction designer must have the view that the purpose of documentation is simply to describe the user interface and the features – the old style “The Name box is where you type your name” type of “help.” But unless the application is very simple, no user will know all the tasks that can be done with it, and might not know what the first step is to accomplish any particular task, much less the sequence of tasks to accomplish a longer scenario. Documentation answers questions, but it also helps users develop new skills they didn’t know they needed.

  • Pingback: Technical Communication: The QA of Product Design | Beyond Help()