Ben Kauffman, Cadence Design Systems, Inc.
Engineers hold the key to much of the information that our groups document; yet, few of us tech pubs folks know how to work well with them. Even in the best of circumstances, the relationship between engineers and doc groups can be tricky. Writers are more than their scribes; engineers are more than our “subject matter experts” (SMEs). We depend on them and — much as they might not like to admit it — they depend on our documentation.
So let’s look at a few ways we can all work more productively with engineers — and vice-versa. Surely our customers would appreciate the fruits of our improved communication.
Reconcile Your Job Functions
Writers are often seen as intermediaries within the R&D organization, but the fact is that engineers serve a similar role. Writers translate and clarify information so that our customers can use our products successfully and effectively. Similarly, engineers translate and clarify information — to implement the designs created by the product architects with whom they work.
Of course, the writer and engineer roles differ, and understanding and processing specifications demands that your writers understand their particular function as opposed to the engineers’. Engineers are most concerned with how things work, while writers — on behalf of their users — should be more concerned with if the thing works and what they can do with it. If engineers were writing documentation for other engineers, they might go through each product feature and discuss how it works. But tech writers must convert that raw information to something that is more easily accessible to the user and that will quickly answer the user’s process-related questions.
Understand Your Differences
In addition to differences in job functions, and thereby goals, writers and engineers often face differences in personality types, as well as in business (and often geographical) culture. Or, as one colleague likes to joke, “The difference between introvert engineers and extrovert engineers is this: The introverts look at their feet while they’re talking to you; the extroverts look at your feet.” While that might overstate a stereotype, it is true that engineers might not communicate as easily — or in the same way — that we documentation types do. And ultimately, sometimes we must get information from engineers a la Malcolm X: “by any means necessary.” Three techniques:
- Work their way. Remember, many of us went into documentation because we’re word people who enjoy reading and writing. Engineers like figuring things out for themselves and will read documentation only as a last resort. So, while email communication might work best for writers and editors prone to long missives, an engineer might prefer a thirty-second phone call to a two-page email, or better yet, to demonstrate a product feature in person.
- Empower the introvert engineer. Give your engineers the office technology to document for you some of their work directly. If you’re documenting a graphical user interface, for instance, you might set them up with a trial copy of a screen recorder (e.g., ViewletBuilder) and encourage them to capture processes for you instead of having to write about them.
- Reuse/Recycle. No one likes having to repeat themselves. Whenever possible, be there when your engineers show sales reps (or each other) the new functionality in an upcoming product release — and if you can, record them.
Most importantly, ensure that your writers understand exactly what engineers are saying, as opposed to simply taking the information they give and making it sound presentable (i.e., “munging” it from engineer-speak into English).
Be Clear about Your Specific Goals
Writers should not assume an engineer knows their level of product expertise. Some engineers will assume the writer knows nothing, while others will assume the writer knows as much as they do. Writers must be very clear about what they do and do not understand — and whatever the case, use their knowledge (or lack of it) to both their own and the engineer’s advantage.
If the writers are novice users, they still must be prepared. They should understand what they don’t know and ask questions. Not only will it help build their own understanding, but their “dumb” questions might well be the same questions that customers will ask. Further, their inexperience might help uncover a bug, defect, or safety concern because they have used the product in a way the engineers had not anticipated.
On the flip side, if a writer actually understands, say, a software tool quite a bit, they might spend some time using the product or running a test case or two so they can ask pointed questions on the specifics of the product. A good technical writer is always curious.
Remind your writers that occasionally they might know more about the big picture inter-functionality of a product and its associated tools than the product engineers, because their work is generally far more specialized than a writer’s. For instance, if writers are putting together airplane repair manuals, the hydraulics engineer they talk to about the landing gear will be different from the electronics engineer they discuss the communication systems with. In other words, the writers might have a better overall working knowledge of the plane in question than either of the engineers who work on its specific systems. Likewise, software engineers tend to work on code for specific functionality, whereas doc writers tend to learn in part by using the product much as an end user might.
Of course, writers should not overstep the bounds of their expertise but, whenever possible, foster open communication that allows for a two-way flow of information. They should not always be asking engineers for help. Engineers should depend on good writers as much as the writers depend on the engineers’ technical expertise. No matter how good a company’s marketing department or field reps are, it is the documentation that often serves as the best advocate for the product the engineers help to create. And the more equal-footed a writer’s working relationship is with the engineers, the more willing those engineers should be to talk with writers and to review documentation.
Get More out of Tech Reviews
The unfortunate reality, of course, is that many engineers approach doc reviews with as much excitement as a trip to the dentist and often think of it as something above and beyond their job. Some fail to understand that documentation, like software code or any other product, is dynamic and ever-changing from one release cycle to the next. That said, there are a few things you and your writers can do to improve feedback from engineers.
- Simplify work for the engineers whenever possible. Obviously, it’s easier to read new sections highlighted by change bars than it is to try to figure out what’s new. As my writer colleague Emma reminds us, “When you ask someone to review a document and they come back saying simply, ‘It looks good,’ don’t assume that they’ve read every word. If you have particular examples or sections that you want them to focus on, you’re better off sending them those pieces separately.”
- Be clear about deadlines. If writers do not specify a deadline, their docs may forever go unreviewed. If there’s one thing precision-minded engineers hate, it’s fuzzy, open-ended thinking, projects, or schedules.
- Think like a project manager. Play to the strengths of each engineer while trying to minimize the weaknesses of others. One engineer might be a great source of examples, while another might be good for skimming your docs cover to cover to make sure all key procedures are included. Still another might actually review new sections thoroughly for technical accuracy. It often takes a fair amount of work to learn the nuances of any team, but writers can get much farther by thinking of their engineering counterparts as part of a team, as opposed to “them.”
In the End
Our brains are all wired differently, and we must work with others accordingly. Or, to paraphrase an old saw: To the optimistic writer, the glass is half full; to the pessimistic writer, the glass is half empty; to the engineer, the glass is twice as big as it needs to be.