“For my work to be admired is one thing, but for my work to be used fulfills my purpose as a craftsman.”
-Mike Mahoney, professional woodturner, Fine Woodworking #255 (July/August 2016)
Things are changing here at Users’ Advocate. Neal has been stolen away by the demands of startup schedules and conference presentations. I could have read his sharp analysis and relatable wit all day, but now it’s my turn to add what I can to the body of thoughtful, insightful , and practical work crafted by Geoff, Mark, and Neal over the years.
So who is this new guy? I don’t plan to fill anyone’s shoes and I can’t claim to be a Thought Leader or a guru. I’ve worked as a tech writer for 20 years. I started in hardware, transitioned to software, managed a team of writers, and now I’m a solo writer responsible for doc production, integration, and distribution for 10+ products, 12+ APIs, and custom-branded solutions for scores of white-label customers around the globe, plus I have a role in internal and external release communication.
I’m a grunt who has spent 20 years fighting in the trenches that separate users’ intention from their success and I’m here to share my experience bridging those trenches. I want this column to be a place where I can chew over interesting issues with like-minded professionals, share practical tips, and express my passion for keeping our users satisfied and successful with information.
As I sifted through topics to write about in this inaugural column, the column’s name kept popping up. What does it mean to be a users’ advocate? Who are these users and why do they need an advocate? How can we best be that advocate?
I found it easiest to tackle these questions by segregating users into two fundamental audiences: external and internal.
External users garner the most attention because their numbers equal success for your organization, either directly as revenue through purchasing and licensing or indirectly as leverage on advertisers, investors, and potential customers. When I studied at De Anza College in the Technical Writing program (now sadly defunct), all classroom instruction and writing projects focused on external users. These high-value users need doc, and your first challenge as a users’ advocate is to produce this doc.
Advocacy, Culture and External Users
A company’s basic culture can present significant obstacles to the writer. In small, nimble companies, the user and the doc can be forgotten in the rush of development and release. In larger companies, the user and doc can get caught in the grind of bureaucracy and interdepartmental politics. It’s unrealistic to expect a writer to single-handedly effect change to a company’s culture, so instead you have to adapt your approach to ensure success.
If your company is fast and loose, don’t fight the rush. Instead, dive into the flow. If your company is ponderous and meticulous, identify the points of friction between teams and inject your curated information as a lubricant.
In both small and large companies, work with program managers. They are the keepers of the lists and ringmasters of the directed chaos. Their job, like yours, crosses organizational divides. They have a greater chance at remaining above political squabbles. Leverage the influence that these professionals have on your organization’s process to make doc a deliberate, considered part of every release and revision. By simply including documentation as a line item in a production readiness checklist or as an enhancement in a product owner’s backlog, you raise your doc’s profile and make it impossible to overlook.
After you make sure your doc exists, now you need to hone it to relevance. It’s too easy to forget that the purpose of your organization is not just developing and releasing products, but developing and releasing products that people are happy to use. Use the product. If you write about software, work with QA to access their early builds and their test plans. If you write about hardware, meet with the lab manager or shop floor manager to request access to components and subassemblies. Walk yourself through assembly and installation. Justify the manager’s trust in you by scrupulously following lab safety and contamination rules.
Whether you work in hardware or software, hook up with product support and technical account managers to ensure that your doc addresses the issues that users actually face. Read industry websites, blogs, and publications. Listen in on product demos and sales presentations, taking particular note of customer feedback. Participate in user and industry communities, both online and in real life at meet-ups and conferences. Immerse yourself in the concepts, concerns, and culture of your users.
External users are not exclusively customers who have already committed to your product. Decision makers, such as prospective customers and auditors, who seek to confirm your product’s features and fitness face their own information challenges that can be met by the users’ advocate.
Ideally, a decision maker picks from a smorgasbord of independent, third-party sources such as reviews, community buzz, and industry analysis. In reality, the decision maker is informed mostly by their own needs that have been stoked by the inherently biased information supplied by your marketing and sales teams.
A tech writer’s work is never completely free of bias. Your documentation must never show your product in a bad light. However, your purpose is not to slant or spin but to provide information, and your users understand this intuitively. In my experience, well produced, comprehensive doc as a tangible artifact of information has an undeniably positive and almost magical effect on decision makers.
Given the flash and glamour of external users and the cash and validation they represent, it should be no surprise that internal users are often neglected by comparison.
I’ve always found this gap sadly perverse.
Internal Users’ Advocacy: Data, Business Value and Managing Up
Internal users engage in building, developing, testing, supporting, maintaining, promoting, and selling your product(s). These critical folks should not be left to fend for themselves and forage for information. A good users’ advocate works to make sure they don’t have to.
Even in the utopian realm of agile with its self-organizing, cross-functional teams, disconnects can happen as a result of personalities, language, culture, and time zones. The users’ advocate can remedy these ills by keeping internal users informed about what doc is available, where it can be found, and when it’s updated. In one agile shop, our chief UX designer, despite sitting in the midst of the app developers, had grown almost completely dependent on the user guide as functional reference to the UIs he was enhancing.
Some of these internal users are executives and managers who judge the value that you bring to the product, to the customer experience, and who decide whether or not your salary is worth the investment. Less enlightened executives often see doc as merely a cost center and as overhead to be contained.
Here you need to manage up. Instead of railing against their shortsightedness or playing the martyr, you must advocate for yourself so that you can be a more effective advocate for your users.
Engage with these internal decision makers so that they have good data that demonstrates how your doc is being used. With Google Analytics, every website now has the facility to track usage and behavior, exactly the sort of empirical data that appeals to the technical and executive mindset.
With good data there’s hope that executives can make good decisions regarding your work and what you can do to keep users happy, including approving the purchase of tools, subscriptions, professional memberships, allowing you time to attend industry conferences and to connect with fellow writers, share your experience, expand your skill set, explore and effect solutions to your communication challenges and ensure that your organization wins.
If you appeal to their intellect, it’s only fair to appeal to their vanity. Remind your execs of the demos they’ve given, the presentations they’ve made, and how their audience always asks for documentation. Remind them of how potent and capable they appear when they can pull out a URL to a healthy knowledge base, a vibrant user community, or even a PDF quick-start guide with more substance than a gossamer whitepaper.
Whether or not you have direct access to C-level executives, you must focus on the craftspeople, the designers, architects, and engineers. These technicians can lose themselves in the immediate task at hand, such as cutting message processing time to under 10 microseconds or hitting ambitious power-density goals.
You as the user advocate need to insinuate yourself into their consciousness and their schedule.
If you’re working in an agile software shop, you need to tape your ears down and dive into the scrum. Hardware is no different. Attend stand-ups and design reviews. It sounds obvious, but you have to know all of your team members by name, not just the managers. Some of the greatest allies in your advocate crusade are like-minded, generous engineers who delight in sharing their work. With their help you can get a jump on the latest stuff when they let you poke at a prototype or when they give you access to their local build.
True Advocacy: Sharing Knowledge… and a Couple of Beers
Of course, the external and internal audiences so neatly distinguished in theory are not so clearly delineated in practice.
For example, one of my first jobs was a contract position writing procedures for an audience of hardware assemblers building large, intricate, and very expensive capital equipment.
I was an excited and bemused baby tech writer on my first day. Even before the novelty of my cleanroom bunny suit wore off, I learned that the assemblers didn’t require doc at all. They knew their jobs inside and out, were steeped to the gills in tribal knowledge, and most were hostile to a contract writer slowing down their builds with questions and documenting their secrets. The true audience for my doc was actually external decision makers, specifically ISO 9000 auditors.
My employer had been hired by a department whose charter was to pass ISO certification. Our sponsor arranged a special session so that we information professionals could document procedures and take pictures of critical subassemblies. We arrived at 6:00 am pushing carts piled high with computers, lights, and cameras only to find a blank spot on the assembly floor where our subject machine had been just the afternoon before.
Turns out that another department’s success hinged on finishing the build for a customer as soon as possible. ISO certification was an abstract concern compared to making a ship date.
I was stuck between two warring factions and faced with my first opportunity to step up and be the users’ advocate. I was too junior to play politics. I wasn’t even an employee of the company, but I had developed a friendly relationship with a chief assembler. He took pity on me and walked me through the procedures on an already assembled exemplar machine. To capture the necessary images, I hit the assembly floor after hours, got on a first-name basis with the security personnel, downed a lot of coffee, and took my captures of other machines in various states of assembly. When I turned in the doc complete and on time, I won a lot of praise and I thanked my shop-floor ally with a case of his favorite beer.
I’m no longer a baby writer, but I still attack my role as users’ advocate with the same enthusiasm. Every day I’m fully engaged, using my soft and hard skills to play with technology and help people. I’m looking forward to engaging with you all through this column and maybe someday even talking shop with you over a pint of your favorite beer.
