Image by Niall Gallagher on Flickr.com, no changes, License
“An adventure is only an inconvenience rightly considered.”
― G.K. Chesterton
I usually think of tech writers and the work that we do in two ways:
- We are paladins, girded in truth, on a crusade against ignorance. Wielding a potent combination of communication skills, process, and technology, we enable user success and engender delight in our product.
- We are skilled and earnest surgeons in a documentation M*A*S*H unit. While under constant fire of doc requests from all quarters, we quickly triage content and apply communication skills, process, and technology like flashing scalpels, patching up our content and sending it back to the front lines to fight for user success.
You could call these portrayals overblown, naïve, or romantic and you would be correct. However, they are ideals that help me get through the day, because, frankly, the workday isn’t always so majestic and the goals and motivations not always so clear cut. Sometimes I have to apply some creativity in my role as users’ advocate and create content for unconventional users whose definition of success is even less conventional–an alt-doc universe.
Contracts
It starts with an email from a coworker you don’t recognize. You might need to check their email sig to figure out who they are. It’s your corporate counsel: “Hey, we’re working on a contract with [big prospective customer]. Do we have any doc on [product name]?”
You haven’t been a part of contract negotiations because, well, you’re a tech writer. Despite this, customers always demand user documentation for expensive, complex products and services that require contract negotiation. Shocking, I know. Suddenly you find yourself working closely with your company’s negotiation team, including executives, sales, and corporate counsel. You don’t know them and they don’t know you and now you need to produce some documentation in a hurry.
In this alt-doc world, you create content for an audience of negotiators and deciders, usually the customer’s executives and legal personnel. Their demands on your doc are often low. The doc req can be as simple as a contract subsection with a list of generic titles like “User Guide, Online Help, Quick Reference Card, Admin Guide, Configuration Guide”. Typically, the fact that the doc exists at all is enough to meet requirements.
You hope you can simply repurpose existing content, because producing this stuff can be dispiriting, especially when it distracts from scheduled work with looming deadlines. Sometimes this work is just plain perverse, such as documenting obscure aspects of a product that no one will ever access solely to fulfill a contractual requirement. And because these docs are often bespoke one-offs, likely as not they’ll never again see the light of day–unless there’s a dispute.
In the end, user success means that the customer is confident, the contract is signed, and the business relationship has been formalized. You can take pride that you contributed materially to that success.
Regulations
If you work as an end-user tech writer in a regulated industry, such as healthcare or finance, you might find yourself writing documentation to satisfy regulatory requirements. The work often resembles writing for contracts–call it alt-alt-docs, if you must… In this scenario, you may not even know your coworkers on the regulatory conformance team. As the tech writer on duty (TWOD), you probably won’t be brought in until very late, usually when your coworkers are in the home stretch of the certification process. The finish line is in sight. All they have to do is complete what they think are the easier, lower-priority line items. As they examine the “Documentation” item more closely, panic sets in, and suddenly they remember that the company has something called a “Documentation Team”. If you’re the TWOD, your phone will ring, or you’ll get an earnest visit. I’ve had a coworker stand next to my desk and ask me for help with a fat sheaf of regulations in his hand, an imploring look in his eyes, and a sheen of sweat on his forehead.
So, if you don’t already have documentation on hand, you’ll be frantically slapping something together so that a checkbox can be ticked during certification. As an added complication, the regulating body may still be busy drafting and interpreting its own rules, leading to some drastic and discouraging swings and reversals.
Although the work can be frustrating and mind-numbing, the “user success” that you contribute to regulation-world is about as significant as you can get: your organization is certified and, quite literally, in business.
Sales
Good documentation inspires confidence in a product, a company, and a purchasing decision. On the surface, all documentation has “thud factor”, whether it’s the actual thud of paper guides or the intellectual thud of a well-integrated support and documentation site. Beyond first impressions, good documentation confirms to the prospect that your company’s commitment extends beyond the sales cycle and that you are invested in their users’ success and satisfaction.
Salespeople know all this. It’s easier to sell something if you have more to offer than a slick pitch. Your salespeople aren’t simply selling a product. They’re selling a success story. Because documentation is such a substantial and conventional part of the success story, I get as many doc reqs and queries from salespeople as I do product managers and support.
Sales requests can be reasonable: an early draft for a product in development or a custom-branded doc set to demonstrate the company’s capabilities and commitment. As we slip into what we could call the anti-alt-doc zone, the requests become silly or bewildering. For example, a long time ago, an executive needed material for a sales meeting with a big prospect. “Print the Javadocs,” he ordered. I pinged him for clarification: Did he mean a few key packages or interfaces? No, he insisted that I print the API doc for the entire system. I couldn’t just say “no”, so I did some quick research. I told him that his request would require 50,000 pages or about 550 pounds of paper, and would not be ready before his afternoon meeting even if we outsourced the printing. He asked for alternatives. I copied our API doc onto his laptop and he made a successful presentation without killing a copse of trees for paper.
When it comes to the work, some common themes should sound familiar by now. As a tech writer, you’re not likely plugged into Sales, so their requests seem arbitrary. The work can be frantic. You’ll burn time and energy on content for prospects that don’t pan out. However, when the customer does “sign on the line which is dotted,” the user success is multifold: your company wins the revenue, the salesperson wins the commission, and you now have a jump start on the documentation.
Information Retrieval
Tech writers work under a good-faith assumption: technical and domain experts provide information that we writers fashion into content for our users.
Now in my experience, a corollary to Murphy’s law is guaranteed–the closer you are to deadline, the more likely that you’ll encounter a key source who breaks this good faith. Sometimes your expert is earnest and knowledgeable, but completely swamped. Other times, your expert doesn’t value you and dismisses you and your work as an annoyance. Well intentioned or not, the net effect of this information starvation is the same: your doc languishes.
What to do?
You could try going over your source’s head. If you have a champion with enough clout, you might get short-term results, but you can also incur some real costs. You could alienate your well-meaning source who now resents you for your org-chart end-run and the additional pressure you’ve brought to bear. And while you might have little to lose with the source who doesn’t respect you, you still run the risk of cultivating a reputation as a snitch who can’t do your job without hiding behind your superiors.
I’ve had success with another approach. Well before a release, if a source goes dark, I stitch together the content as well as I can with my limited resources. Then I distribute the doc as a release candidate.
I admit that the first time I tried this, I did it out of frustration and desperation. I risked appearing clueless and reckless, but over the years I’ve learned that the risk is mitigated by the end result: better docs. My shambling Frankenstein’s monster of a doc usually has a galvanizing effect on people. Here are some examples of “user success” I’ve had over the years:
- The errors in my doc delight my source with the opportunity to correct me.
- The gaps in my doc trigger the perfectionist in my source and compel them to fill in the blanks.
- My source still doesn’t like me, but now they can play the role of patronizing guru to the gormless tech writer.
- The sad state of the doc for their product shames the source into action.
- The doc lures out other experts, hidden gems, who step up and speak out to fill in the blanks.
- My decoy doc falls into the the hands of an executive or a senior manager who then whips folks into action. This is similar to going over the source’s head, but any resentment is often directed at the goading executive.
- My source drops a thick stack of feedback on my desk because some folks just respond better when they have something concrete and structured to comment and critique. For example, one of my favorite product managers is a superstar reviewer as long as I give him something he can print out and scribble on. I’ve had scribbles overnighted to me. I happily sign for them.
Dividends
So not every day is a triumph. Some days strain my definition of both user and advocate. Others strain my patience and my sanity. Although these diversions from the norm feel like a burden and an inconvenience, they are actually adventures.
You remember your adventures and you learn from them. No matter how grueling, I take away sharper skills after writing under tighter schedules for new audiences. I develop relationships with coworkers beyond the traditional tech-writer circles. And when the alt-doc adventure is finally over, I’m gratified to come home to my familiar, comfortable, end-user content and get back to work with renewed appreciation and new perspectives.
