Part IV: Enabling information flow
- Docs aren’t the espresso machine
- Outsourcing doc needs
- The value of information flow
- The value of information flow
Our argument about the value of documentation has taken on some challenges. It’s not enough that documentation has value through perceived high usage among important groups — so do other resources in the organization. Both the photocopier and espresso machine have high usage among in the company, but with a finite budget, how do we choose which resource to retain? We still haven’t proven that documentation has a higher value than some other needed company resource.
Docs aren’t the espresso machine
One problem is that docs aren’t sexy — they don’t have a high value or esteem in an organization. Many people dislike the very idea of docs. As mentioned earlier, for UX designers, the inclusion of docs might suggest a failure in design. For product managers, the idea that their product (which is supposed to be easy and intuitive to use) should actually require a lot of documentation also suggests failure. Imagine product managers chatting with each other: Your product needed documentation for users to understand it? Oh, my products are so intuitive, our users don’t even need documentation. Docs are like a crutch for a product that should stand on its own.
Users, too, do not welcome a hefty user guide. A writer once described the sound a thick manual plunking down on a desk as an “almighty thud” — the thud fills users with despair for all the learning that will be required.
If docs are our only contribution, and almost everyone dislikes the idea of docs, will we ever rise above our low place on the totem pole of value? Can we move past the idea that technical writers merely contribute documentation? What would our additional forms of value look like?
Outsourcing doc needs
If the only value technical writers provide to an organization is documentation, their value may eventually be outsourced. Here’s an experience to illustrate. I once worked for a non-profit corporation in Utah where we tracked our time against various cost centers. For example, if you worked 3 hours on Project ACME for the day, you entered this into a time tracking spreadsheet, applying the 3 hours toward Department X. Inside the corporation, each department had a certain budget of how much they could spend. Our time spent on documentation for their department was applied against their budget.
We thought the setup was just some annoying accountant trying to track spending. But one day, the company announced that they were laying off all the technical writers (in addition to about 7% of the total IT workforce). This shocked us. We didn’t think they would remove an entire function within an organization. Maybe 1-2 writers, but not everyone. But alas, it was true. Audios, writer amigos!
In retrospect, I think this is what happened. Behind the scenes, some bow-tie-wearing, clever accountant was doing an internal-versus-external cost analysis, similar to a buy-versus-build cost analysis. Was it cheaper to employ full-time technical writers at, say, $80 an hour, or to outsource technical writing needs to an external vendor for $60 an hour? The decision must have been to outsource because it was less expensive, and the company would still get documentation in the end.
The corporation provided generous compensation packages, and I made my way to California and started a new life there. Over time, I learned that the corporation hired some of the tech writers it laid off as long-term external vendors and paid them more than they were earning as salaried employees. Some departments even re-hired full-time technical writers on an individual basis (rather than having a centralized tech writing team). So clearly, the decision to outsource as a way to cut expenses was not a slam-dunk for cost savings as the accountant had hoped. Why not?
One reason may be that, ultimately, documentation wasn’t the only value the tech writers provided. Contract technical writers are contracted to provide one service: documentation. Because the contractor’s role is fixed around this end, the contractor can cheapen the rate, charging only $60 an hour and coming across as less expensive than the full-time salaried technical writer.
But the contract technical writer is not going to provide any of the extra services that are typically included in the salaried technical writer’s role. The contract technical writer will write only the needed documentation topics as specified by the contract. The additional services not included by the contractor might be as follows:
- Testing out the instructions in detailed ways (maybe even trying to break the system)
- Logging bugs when identified
- Providing user interface feedback
- Analyzing trending support logs, and then providing documentation to address these trends
- Setting up and maintaining the authoring and publishing system
- Maintaining existing documentation over the life of the product with each new release
- Informing other groups, across organizational boundaries, about relevant docs and information
- Training field engineers on the new functionality
- Meeting with field engineers to gather input about user pain points, and then relaying those pain points back to engineering teams and UX designers to improve the product
- Working with Marketing groups to review upcoming blog posts and ensure the information syncs with the documentation harmoniously
- Staying abreast of industry trends around the product to identify information needs in the documentation and product, and so on.
Contractors avoid these additional tasks because these activities drain their time, and they agreed only to write the given documentation. Salaried technical writers tend to perform these other activities, though they often don’t get credit for them and the activities go unnoticed. For example, the only resource tracked in that accounting spreadsheet is “hours” for “documentation.”
If all a company does is analyze hours for documentation, the tech writer will eventually be outsourced because it’s simply cheaper to get documentation from an outside vendor. As more support for this idea, follow this thought experiment.
Suppose you were to start selling documentation as a product to other groups in the company who need it. Do you need documentation for Project X? All right, based on the estimated 50 pages needed, we will charge $16,000 for the documentation. (50 pages x 4 hrs per page X $80/hr = $16,000.)
This might seem like an ingenious way to assign a direct value to documentation. It would tell you exactly how much your documentation is worth, right? If the groups won’t pay the money, documentation isn’t worth the cost. But you hope they will pay it because surely they can’t release a product without documentation.
But now Department X starts doing some research. Although your tech writing team wants to charge $16,000, they find that a contractor will do it for $10,000. This becomes a no-brainer. They just saved $6,000, which they can use to pay an intern to do even more work.
I’d love to find examples of tech comm groups that actually started charging for docs to see if my thought experiment is correct. But my point is this: It’s not enough to just provide documentation. Tech writers must provide additional value to the organization. Where might this additional value come from? One benefit might be to foster information flow within the organization.
The value of information flow
What do I mean by information flow? Consider the graphic I previously used to show the many groups that use documentation. Now let’s pivot the graphic to show how information might flow through these same groups:
Because technical writers are at the intersection of these groups, we are poised to enable information flow through these lines. We don’t just document the needed information and publish it; we channel the information to the right group that needs it, and we pull information from other groups that have it. We connect information across groups, bringing information through these pipelines and pulling together the right people into conversations.
In earlier research I cited the work on value by Emily January Petersen, who noted:
Practitioners know that TPC crosses boundaries and is therefore networked in a way that no other profession currently is.
If tech comm is networked in a way that no other profession currently is, can we use that deep networking to leverage additional forms of value?
Hughes also noted that dissemination of the knowledge assets we create is a natural action for technical communicators to take:
Technical communicators who see themselves as creators of knowledge think beyond the concept of documentation and think in terms of knowledge management systems. Writing becomes a secondary and subordinate activity to content management. The user community becomes just one of many stakeholders who can benefit from the knowledge the technical communicator has created, and the technical communicator seeks ways to distribute that knowledge to all the stakeholders—for example, marketing, operations, engineering, and so forth.
With arguments about information flow, we are moving towards knowledge management functions as a form of additional value in a company.
Here’s a more concrete example of how information flow might work. I’m currently creating documentation for the APK upload process with app submission. I’m pulling information from trends identified by Support. I’m also interacting with field engineers to identify issues with APKs for the customers they work with. As I improve the documentation around APK uploading, I’ll channel the feedback to the UX team, who is redesigning this area of the submission console. I’ll also let engineers know what specific pain points users have with the APK processing. When I finish the docs, I’ll let Marketing know so they can potentially highlight the new design as an incentive to show continued improvement for app developers. Business development can benefit from knowing that some previous issues have been resolved or clarified so that they can speak more persuasively to prospective clients. I’ll also let Support know about the updates so their forum responses can leverage the new content. And all of this chatter will surely draw Ccs and input from people whom I don’t even know should be involved in the discussion!
As a technical writer, I can foster this conversation because all of these groups have intersecting interests through documentation. The work I’m doing has some relevance to all of them, and I can involve them, get information from them, and connect them with each other in conversation-enabling ways that make information flow.
In the most recent issue of Technical Communication, Sarah Martin et al argue that technical communicators are in a key position to provide organizational value due to their intersection with other groups. They write,
Wilson and Wolford (2017) remind us that TCs [technical communicators] are “almost always located at the nexus of data, language, and meaning, trafficking in expanding economies of information within organizations” (p. 5). As such, TCs, through their user-centered approach, can add value to a variety of workplace initiatives (Dubinsky, 2004). Promoting User Advocacy to Shift Technical Communication Identity and Value
Their focus is on playing user advocate roles with user experience design, but tech writers can play many more roles as well.
Too often, technical writers work in isolation, not interacting with other groups much at all. We sometimes accept this interactivity by describing ourselves as introverts. Maybe in the back of our minds, we imagine ourselves as a writer sequestered away in remote, isolated cabin working on a novel for years? But it shouldn’t be like this. Technical writers can be the primary force behind information flow within an organization. By increasing our interaction with the groups, we can not only inform them but more accurately identify and meet their needs. Tech writers have a big picture perspective in an organization that allows them to see across teams and connect the right people together with needed information.
Helping needed information flow across these different groups is not merely a byproduct of docs or a side role to play. This flow of information across all the groups actually helps technical writers create better documentation. The interactions elicit input from these other groups in ways that can dramatically inform and improve the documentation. The more information tech writers move around, the better the docs get. The better the docs get, the more they empower others in their roles.
More interactions with these groups also lead to higher perceptions of your value to these groups, regardless of any metrics or financial ROI backing up the claim. Remember, at the end of the day, it is these perceptions that matter and drive business decisions.
The value of information flow
Some business analysts argue that information flow is a key to successful companies. Imagine a company where each group is siloed from the others, not communicating or sharing or interacting. In such a company, the consequences of these silos might include redundant services, duplicate efforts, decisions made from missing data, etc. — the lack of information can undermine the company’s strategic objectives.
For example, many analysts blame 9/11 on shortcomings in the information flow within intelligence agencies. Each group’s inability to share information within the large organization led to blindness in recognizing warning signs that were occurring. In Knowledge Management in Theory and Practice, the authors explain:
After 9/11, we asked ourselves: why was no one able to connect the dots? (David Ignatius, Associate Editor, The Washington Post). Could 9/11 have been prevented? In a number of critical cases, mishandled intelligence, bureaucratic tangles and legal hurdles blinded the CIA and the FBI to clues right in front of them. Individually, none of these was a smoking gun. But combined they were a four-alarm fire. (Frank 2004). Knowledge Management in Theory and Practice. By Kimiz Dakir, Jay Liebowitz.
To fix the issue, they encouraged information flow by creating a collaborative wiki (Intellipedia) that would allow better cross-department communication and sharing of information.
We’re not looking for signs of terrorist activity in an organization, but surely this information can help avoid product disasters and inform high-level strategies. If information flow is a high-value benefit of technical writers, this goal should inform the way we go about documentation roles.
In the Harvard Business Review, authors Nielson et al explore principles for “successful strategic execution.” One of the principles is that “Information flows freely across organizational boundaries.” The authors relate this anecdote that shows the danger of lack of information flow in an organization:
A cautionary tale comes from a business-to-business company whose customer and product teams failed to collaborate in serving a key segment: large, cross-product customers. To manage relationships with important clients, the company had established a customer-focused marketing group, which developed customer outreach programs, innovative pricing models, and tailored promotions and discounts. But this group issued no clear and consistent reports of its initiatives and progress to the product units and had difficulty securing time with the regular cross-unit management to discuss key performance issues. Each product unit communicated and planned in its own way, and it took tremendous energy for the customer group to understand the units’ various priorities and tailor communications to each one. So the units were not aware, and had little faith, that this new division was making constructive inroads into a key customer segment. Conversely (and predictably), the customer team felt the units paid only perfunctory attention to its plans and couldn’t get their cooperation on issues critical to multiproduct customers, such as potential trade-offs and volume discounts. … as the market became more competitive, customers began to view the firm as unreliable and, generally, as a difficult supplier, and they became increasingly reluctant to enter into favorable relationships. — The Secrets to Successful Strategy Execution
Who better to unstick companies from this inertia than the very group through which almost every role interacts? Tech writers can play a tremendous role in the information flow in a company — if we see it as part of the value we add. As such, tech writers should not be siloed, introverted groups with their heads down typing away for months creating docs in isolation. We should see ourselves as an interactive group that moves information through many parts of an organization, connecting groups together and making the right parties aware of the information they need. This information can be the lifeblood of effective decisions that lead to successful outcomes for a company.
In the job description for technical writers at Google, the description reads:
Technical writers play a big part at Google. They are a key link between engineers, marketing associates, developer advocates, as well as all the external users and developers, tying together many vital but disparate parts of the Google ecosystem. (careers.google.com)
Google seems to get this hidden value that tech writers can play. The documentation role connects these groups together. The larger the organization (such as Google’s size), the more such a connecting role becomes relevant. A small startup doesn’t have nearly the same information flow needs as a technology giant, but it is still an important contribution.
Let’s return to the scenario of the poor photocopy machine that is likely going to be replaced by the larger fridge, watercooler, and espresso machine in the breakroom. The photocopier’s original function was to provide documents — scans, copies, faxes, etc., of important agreements, proposals, and other items for review, annotation, signing, and so on.
What if the photocopier didn’t just perform these document-related functions but also did something more? Already, all employees in the department send jobs to the photocopier by way of the network through a printer queue. The photocopier just happens to be the intersection point through which nearly every employee’s work flows. Suppose the printer’s job-queue software gets an enhancement that amplifies its intelligence about jobs processed. The software now captures the document title, metadata, and sender, and then performs comparative analysis on these print jobs to match similar document titles with senders. And not just within the same department, but across the entire company. Each manager can now access a report of documents flowing through the system to see what types of documents are being printed, who is sending them, and more importantly, where similar roles and documents overlap across the entire organization.
Now that photocopier versus fridge / watercooler / espresso machine decision is more complicated. This photocopier has a potentially interesting ability to deliver strategic information to the organization. The department manager is curious to know what Max is printing so frequently in the copy room, but more importantly, she’s interested to know if other groups handle NDA agreements, and how they process them because it’s a major slow-down in her group. They have to route these NDA agreements through several legal bureaucrats before round-tripping them to customers, and it’s insanely slow. Maybe the photocopier’s network and job intelligence can give her some insight, gleaned from other NDA-processing groups, that will help her become a better manager?
Are you still going for the fridge / watercooler / espresso machine? Or are you now leaning towards the photocopier?
Although enabling information flow provides strategic enablement in an organization, it’s nearly impossible to measure, and the task doesn’t entirely connect in with the technical writers’ main skillset, which involves content development. How can we marry the idea of information flow with the technical writer’s strength of content development? This brings me to the next idea station in this essay: Content Experience.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.