As a technical writer, are you finding yourself wishing for just a bit of respect from the engineers, SMEs (Subject Matter Experts), or other technical people you work with? Are you finding that these folks seem to stonewall you on every question you have or every goal you’re trying to achieve? Are they obstreperous? Difficult? Or just plain unhelpful?
When I hear technical writers complaining about–er, describing–such troubles when working in a team environment, my first reaction is to want to sit and observe how they actually interact with those seemingly impossible team members. In my experience, I’ve found that the problem isn’t always with a surly SME or with an engineer who lacks communication skills. Certainly, there are cases where other team members just don’t value any contribution other than their own; however, most often, I have found the problem is with the technical writer’s approach to the team environment–and have found that the problem began from the very start of that writer’s involvement with the team.
In this article, I offer techniques for approaching a new team and for working in a technical team environment. As you’ll see, the key is not “getting respect” from your techie teammates but, instead, establishing and building mutual respect with them. This information is presented from a software development environment–where the team is primarily made up of developers–but would apply to many other team environments.
Start By Learning
No matter how much you know, you probably don’t know enough. Team environments are inherently complex–involving not only the team players, their roles, and their contributions, but also the project, technologies, needs, audience, and politics, among other things. So, when approaching a new team, don’t start by doing, re-doing, or un-doing; instead, start by learning:
Meet the developers . To begin, simply find out where they sit, and go introduce yourself. Even if your boss walked you around to meet people on your first day on the job, take a second walk on your own. If you already met the developers in the interview, this is your chance to recast the relationship as one of teammates–not someone on the outside checking out the inside (and vice versa). Get out of your cubicle, bring a smile, and extend a handshake. Then, don’t talk about yourself. Although you may be tempted to talk about your experience, education, expertise, or skills that you’ll contribute to the team, don’t. Instead, ask them questions about the projects–how the projects came about, what the goals are, what obstacles the developers face, and how they’re coming along. And, ask about their role(s) in the projects and other projects they’ve worked on.
Listen actively. As you gather information about the project, product, audience, and documentation needs, maximize your time with others by understanding the answers to the questions you ask. Take time to understand the answers others give you–right then and there. Invariably, even the most cantankerous souls–who would skewer you two weeks later for asking the same question again–will bear with you while you puzzle out an issue. Actively restate the answers until you have them right.
Try everything out. Get a copy of the previous version of the software (if such a thing exists) and the documentation (hardcopy and online), and try it all out. When something doesn’t work as expected, ask why. After development code is available (even–or especially–alpha code), make sure that you’re installing and using it as often as possible. Depending on what’s available to you, you might also go a step further and set up a test system for your own use. Make sure you understand both “How do I do ThusAndSo” and “Why would a customer want to do ThusAndSo,” and keep those aspects in mind as you proceed with your documentation projects.
Solicit customer/user input. Starting on your first day, identify people in the organization who could provide direct or anecdotal customer data, then keep following up with them until you learn what you need to learn. Keep questions such as, “How do customers feel about this,” “Do customers use this in this way,” and similar questions in mind from the outset of the project.
Make sure that you’re on the same email aliases and mailing lists the developers are. You should be able to watch (and participate in) all of the online discussions of design, implementation, and bug fixing, and see comments from marketing, customers, and management. Sometimes organizationally-based lists–ones that include only Manager Jane’s direct employees, for example–will be used for this kind of communication, and you might not be welcome. Resist that, though: Getting into the loop as part of the team is crucial, and you cannot do that if you’re not privy to the discussions.
Make sure you attend all of the meetings at which project-related decisions are made. Perhaps this means that you end up going to both a technical publications staff meeting and one or more staff meetings for development teams. Or perhaps you convince the development team to keep personnel issues in the staff meeting and to have a separate technical meeting for project issues. Either way, you must be involved. Be nice, but on this issue and the preceding one, be very firm and persistent. “I need to know what’s going on with the product to be able to document it effectively” is a very hard statement for anyone to argue with; if they tell you you’ll be bored, gracefully accept that risk. Then, of course, pay attention, use those meetings (and discussions) as learning opportunities, ask questions, and build your understanding.
Keep “Team” in Mind at All Times
As you approach your new technical writing position and environment, keep in mind the fact that you’re working as part of a team–working toward common goals, deadlines, and successes:
Your job is to contribute to the team. It’s easy to think of your job in terms of contributing pages of documents, developing piles of books, and writing scores of online help files. That said, it’s a rare project in which contributing more information is the best contribution a writer can make. More often, winnowing the informational wheat from the chaff of data is a better contribution to the overall goals of the team.
Know the project and team thoroughly before launching pet projects. As you get started in your job, you may be tempted to start a project of your own–launching an audience analysis project or redoing an existing documentation project, for example. While you may think that starting off with a tangible project with tangible results might be the best way to show your stuff, it’s likely not. Instead, you should first become intimately familiar with the project, product, and team before launching any pet project. For example, although you should indeed solicit customer input of any sort in any way you can get it and should go out of your way to stumble across it, launching an audience analysis pet project before you know the team, the developers, and the product thoroughly indicates that you perhaps aren’t as engaged with the product, team, and goals as you might be. What’s more–in this example–although understanding audience needs is key to developing effective documentation, understanding audience needs in the context of the project or product will always yield better results.
Show, don’t tell. Even if you re a whiz at GUI (Graphical User Interface) development, testing, and UI (User Interface) design, in addition to being a stellar writer, don’t tell everyone right up front. As a matter of fact, if you’re that good, they’ll notice. Concentrate on dealing with the project documents you’re working on, and your other areas of expertise will come through. For example, through discussions with the developers about the design of a wizard, you could demonstrate your usability expertise. (See also “Help out whenever possible” toward the end of the article for more ideas on demonstrating skills.) And, along those same lines….
Communicate proactively and positively. If you notice problems, issues, or questions with the product, take time to reproduce the problem (and ensure it’s really a problem and not user error!) and then bring up the problem to the appropriate person: “Steve, I expected the FazButton to do ThusAndSo, but it didn’t. I encountered the problem twice while doing ThusAndSo. Did I goof, or is there a step I’m missing?” Until you have a well-established relationship founded on mutual respect with the developers, shy away from “this is a bug,” or “this needs to be fixed.” Some developers don’t mind, but others react as some writers would to a developer commenting “what’s your point?” about something they wrote. Your goal is to show the developer the issue and let her apply the “bug” term, if warranted. Your best contribution is in actually using the product–as a customer would–and in identifying potential issues. Fighting the “is-a-bug/not-a-bug” wars is not compatible with this goal.
Dive into the product, not just the documentation. One of the best ways to establish and build mutual respect with developers is to understand what’s behind the products. For example, find out if you can get the developer code–and install it on a test machine or even on your desktop system. If you’re not comfortable doing this, that’s good; it means that you will likely learn more than just what’s behind the product. Even if you can’t read the code–yet–you can learn from the code comments (often included to describe the code) and perhaps be able to grasp a rudimentary understanding of how the code pieces fit together. If your technical skills aren’t sophisticated enough to compile and install the code on your own, ask a developer to help. She will probably be glad to see you take the initiative to understand what’s behind the product.
Likewise, if you’re running the software and find an error message or bug, take a second to search the code for the message. This can sometimes be very enlightening–and help you more effectively work with developers. For example, if you get an unexpected error message that states:
Install a Web browser before completing the process
but code immediately above the error message says:
// Print error message if no internet connection available
you can easily surmise that there was a whoops on someone’s part, and provide more complete information about the problem to the development team.
Taking such proactive steps to understand what’s behind the product can go miles toward showing you’re not just there to “write documentation,” but there as part of the development team. And, you’ll learn a lot along the way and improve your technical skills.
Be aware of the climate and schedule. If the developers are on deadline and you have needs that really can wait or have later deadlines, then give the developers a break. Tell them you’re doing so–just so they know that you’ve not vanished–but say, “I understand that you’re all swamped, so I’m working on other stuff and will not bother you for a while. But, after you’ve met your deadline, I’ll need some attention to ThusAndSo issues I’m deferring now.” They’ll appreciate it, and they’ll “get it.”
Don’t Make (or Try to Make) Gratuitous Changes
Along the lines of building an understanding before you try to produce anything, do not enter a new team situation trying to change things:
Use existing processes. Maybe you previously used a highly-successful process at another company for tracking product and document changes, and you want to introduce it to your new team. You may ultimately be right–perhaps their current process is far from perfect and your idea would be better; however, especially as you enter a new team, don’t start off by trying to change existing processes. Likely, those processes that you’re sure could be improved upon came about through a history of issues, decisions, and needs, and you need to take time to understand that history before even thinking of suggesting a change. So, for example, if the developers file every nitpick with the product as a “bug,” do the same (and expect the same for your documents). If the team uses an informal email exchange about the severity and appropriate handling of problems, participate in and instigate such discussions, rather than filing a bug. When in Rome….
Use available tools. The writing tools they give you to start out with are fine. Really. No matter what they are. Like existing processes, the tools you have available are likely also a result of a long history or issues, decisions, and needs, and suggesting a change before understanding that history will likely ruffle some feathers. Further, consider that tools are also often part of the process, and changing the tools–no matter how right you may ultimately be in your suggestion–will require time, resources, and other changes that the team may not currently have time to accommodate. Besides, as you’re learning the ropes of the product and team, do you really have time to make such a change?
Use existing documents as learning tools, not as opportunities to make changes. Even if the documentation you inherited is the all-time prize-winner in soporific reading, don’t change anything. Yet. Why? Two reasons: First, you need to understand how the documentation set came to be before you make changes. For example, a stilted style and awkward format could be just the ticket for an audience of retired military personnel. Second, until you really understand the political lay of the land and the decision-making process that resulted in the documentation, you could permanently damage your status by implicitly or explicitly criticizing the existing documentation. If changes are to be made, they should be driven by serving customers better, and you don’t yet know enough for that when you first start.
Live with existing styles, conventions, and guidelines. Although you may disagree with what the style guide says or have good reason to break the stated conventions, when starting a new job, those issues can wait. There’s nothing more disturbing to a development team than a new member who is already looking to reinvent the wheel. Definitely, definitely don’t address issues like serial commas, preferred style guides, or excising passive voice from all the documentation. As a new member of the development team, you have bigger issues to address–namely learning the project, product, and team–and you’ll simply seem disengaged if your priorities appear to put form over function.
Get Involved
One of the best ways to become a valued team member is simply to become involved. Not only will doing so help you contribute, but will also provide a range of learning opportunities and opportunities to demonstrate your skills. In short, becoming involved–in a range of projects, yet not so many that you’re stretched too thin–can take you from “valued” to “indispensable”:
Take responsibility. When a documentation-related issue comes up, take responsibility for it. If the problem stemmed from a bug from the previous version of the software, take responsibility for the documentation-related problem. If it’s an oversight in early drafts, it’s yours. If it’s an egregious error in the final shipping documentation, it’s yours. Of course, do this without making excuses, pointing fingers, or arguing about it. Just take responsibility–even if 17 developers told you it was right before the documentation was shipped–and resolve to do better next time.
Help out whenever possible. If a communication-related issue comes up–be it UI text, error messages, specification documents, approval-process related documents, or whatever–offer to help out. Do not jump in on day one (or necessarily on day 100) and claim ownership, but if there’s a problem with, say, the text of an error message that nobody else wants to deal with, take the opportunity to help out. Doing so has two advantages: First, you show that you’re a team player and you’re willing to use your skills and expertise to help the team as a whole. Second, every GUI issue and error message you fix makes your documentation that much simpler and easier to write.
Conclusion
So, if you’re finding yourself wishing for a bit of respect or having problems with the techier members of the teams you work on, look closely at how you began your interactions with the team and how you currently interact. You may indeed have truly surly, unhelpful, or unwilling team members to deal with, but you may also find that you can take steps to improve relations and build mutual respect with them.
