Transparency in documentation: dealing with limits about what you can and cannot say
- Sample scenario with documentation and transparency
- Transparency in documentation
- When I worked in Marketing
- When I was in a controlling religious institution
- Blogging and transparency
- Developer documentation and transparency
- Conclusion
Listen here:
Sample scenario with documentation and transparency
Scenarios in which marketing or product managers ask tech writers to filter information out of docs aren’t new. The other week on the Write the Docs Slack channel, during a discussion about how to handle documentation for broken products, someone said,
I remember a colleague at a previous job getting told off for prefacing some instructions with something along the lines of: “You need to follow every step of these instructions to the letter, even if they seem weird or pointless, otherwise the whole thing will break.” … It was a fantastic way (IMO) of demonstrating just how broken the product was.
Many of us work on user interfaces that are less than stellar. In fact, the phrase, “we’ll add a note in the docs,” used in the final hour before a product release to address some critical issues discovered too late to fix, is heard so commonly among technical writers that we hardly wince anymore, we just nod.
Other times a product might not be broken; it might just be missing key features that users want. In these scenarios, product managers often prefer to document what is possible and quietly omit mentioning what is not possible, even when the unmentioned features are surely ones users will ask about.
Usually the project manager doesn’t want you (as a tech writer) to include the information about these missing features for fear that the documentation will generate negativity or other resentment among the users. Perhaps in product or marketing manager’s minds, this information would play out as follows in the user’s head:
[User reads instructions…] You can’t control the timer setting on the gizmo. What?!!! Oh heck, I didn’t even realize how much I needed a timer setting feature. Now that I realize I can’t adjust the timer, I want to adjust it even more! I must be able to have all power and autonomy over this device. Anger anger anger!!!
Product and marketing managers would rather keep users in a state of unknown unknowns. What users don’t know can’t make them upset. But by revealing to users the product’s limitations, we introduce awareness of these limitations and henceforth frustration/anger among users. (At least this is the product manager mentality as I understand it.)
In reality, users are often perfectly aware of product limitations. Maybe not at first. Often the features within a system may have weaknesses or other issues that only become apparent later, after more use.
As a technical writer who documents the system in great detail, you often have intimate knowledge that, if shared, would potentially turn users off from the start. You know the weak spots and other problem areas in your software. Do you let users know too?
This scenario has surfaced a few times in my career, and it’s always difficult for me because I prefer to err on the side of over-transparency, while marketing and product managers prefer little to no transparency at all.
Transparency in documentation
I feel pretty strongly about the need for transparency in documentation, especially when describing the limits or shortcomings of a system that users will want to know about. I didn’t realize how strongly I felt about this until I had a recent project where this issue came up.
During the project, I had some days where I could hardly concentrate on my audio books during my 8-mile bike rides to and from work. I would feel my tension getting worked up at night just thinking about it. I couldn’t concentrate. The issue kept invading my mind and detouring me.
Then I wondered, introspectively, why was I getting so worked up over this? Why did this matter so much to me? Whether I included all the information users wanted or not … who the heck really cares? It’s not, after all, my own product that I’m selling. I just work for a company that employs me to write, and this is the message they want to communicate. So I obliged with product and marketing requests, but not without a bit of resistance.
The experience made me think about my own values and why this issue of transparency might have been more close to home than it is for others. Was it close to home because of my previous time in marketing? Was it close to home due to my previous history with religion? My values as a blogger? My focus on developer documentation? Something else?
Let me go through each possibility with a little more detail.
When I worked in Marketing
Earlier in my career, before turning to technical writing, I actually worked as a marketing copywriter. Being a marketing copywriter for a new product that you think everyone should happily own might be a fun job. But I was a copywriter for an alternative health and nutrition company, so I spent a lot of time and energy coming up with creative ways to write about protein pills and treatments like chelation, detoxification, and hyperbaric chambers. (Pretty much on par with homeopathy and astrology.)
The core product was protein pills. Based on all the research I read online, it seemed clear that you get enough protein in your daily diet (especially meat-eating Americans), without the need for supplements. You don’t need to add more protein into your body unless you’re a triathlete who is half way through a body-emptying race and your muscles are so depleted they’re literally eating themselves.
Despite the fact that I never used the company’s products myself, I wrote with great enthusiasm and energy. (The company was either too cheap to give me free samples, or they feared that if I tried the products and found they did nothing, I’d lose motivation to write rock-star sizzling copy that resulted in sales … or so I thought).
But I didn’t care about the ethics behind writing marketing copy for products I wouldn’t buy myself. I would have been just as happy to spend my time writing copy for premium slug salt or re-usable pop cans or designer koozies — this didn’t bother me one bit.
As a budding marketing copywriter, I didn’t care because I was writing! I had left teaching behind me (sorry students, I never liked grading your essays). I was a full-fledged writer now and I was cracking away at articles that others were reading.
I might have continued as a marketing copywriter if the pay were decent, but the pay was dismal. In 2004, my entry-level copywriter job paid $33,000/year. That was unsustainable. I ended up turning to tech writing to survive.
In the end, I didn’t leave marketing copywriting out of a penchant for “honest and truthful information.” I know we like to refer to Marketing as “the dark side,” because it’s full of shiny, fluffy copy that lacks substance, promises everything, and constantly re-assures readers that the product is “easy to use.” No, I was happy to stretch the truth. In fact, I took it as a challenge. The more useless or ridiculous the product, the more fun it was to write copy for it.
So if Marketing copy and its lies didn’t bother me, why did my recent documentation project, which seemed to veer from technical information into Marketing’s dark side, unsettle me so much?
When I was in a controlling religious institution
It could be that my 20 years inside a controlling religious institution (that is, the Mormon church) contributed to my distaste for information distortion. As a teenager, I became best friends with a Mormon kid and ended up joining the Mormons. (This was before the Internet, FYI.)
I spent many years going through the traditional Mormon channels (from BYU to mission to temple marriage to leadership callings) before finally waking up and realizing that I was in a controlling religious institution that was sanitizing, whitewashing, distorting, and hiding its history.
My awakening didn’t happen overnight. I had a long trajectory of dissatisfaction with many years of empty Sundays expressing frustration about information that wasn’t included when it should have been (like biographies of Joseph Smith in Sunday School manuals that casually portrayed him as monogamous).
It wasn’t until my wife woke me up to the rampant sexism and patriarchy that we decided to finally disassociate ourselves (and more importantly, our 4 young impressionable daughters) from the faith (and all faith, actually).
From that experience, which consumed a good chunk of my life, I have a deep skepticism toward institutions — not just religious institutions, but any controlling institution that tries to steer people to believe sanitized, filtered information.
I think a lot of things are a scam now. Even my local optometrist and those 2-year prescription renewals that are required before you can re-order contacts seem like a scam to me. (I’m more guarded than I should be, probably.)
When I turned to technical writing, I found it to be a natural fit and home for value set. There would be no more distortion or manipulation of the facts in my career.
Indeed, there is perhaps no other job that allows you to write with the same degree of plain-speaking truth, creating information that helps others. If we can’t do this, if we are forced to sanitize and filter information at the user’s expense, then aren’t we participating in some kind of controlling institution?
In the reasons for my uneasiness with information filtering, I think my Mormon background ranks high.
Blogging and transparency
Here’s another potential reason for uneasiness: I’m also a blogger, and all good bloggers place a high sense of value on transparency. Transparency is what earns your trust with readers.
Back in 2009, I wrote a series of posts about the “7 Deadly Sins of Blogging.” I said Sin #1 was Being fake. In the post, I quote a pro blogger who explains that trust is the blogger’s currency. Tony Hung explains:
At the end of the day, trust is the only real currency in the blogosphere, and people who read blogs have the expectation that they’re getting at the truth — in whatever form the truth is to them. And because there is the presumption of truth, readers will often react in an intense fashion to being manipulated, hoodwinked, and otherwise bamboozled. The Rules Behind Creating a Great Blog
Transparency was as important at the beginning of blogging as it is today. The lack of transparency is why corporate blogs never took off and never will. Corporate blogs are little more than a variant of the press release.
I’m not quite sure why Marketing (and by association, Product Management) don’t seem to get the importance of transparency. On the Internet, you can’t withhold or control information for very long. You can’t control information because we no longer live in a decentralized information model. There isn’t someone at the top who is controlling and deciding which information reaches the peons at the bottom.
If information is lacking in the official docs, Joe Blogger will post the information on his site, and then it will appear in google searches when people look for the information. Worse, when you don’t provide the information on your own site, you relinquish control of the narrative. You let Joe Blogger tell the story of this highly sensitive topic that you chose to omit from your documentation.
If Joe Blogger doesn’t write about it, Francis Forum-Goer will ask about it in the forums. Then your support team will provide the information. Francis will reply with clarifying questions, and you’ll have a nice long thread full of raw, potentially heated user emotions underlying the highly sensitive topic.
You can’t hide information or control the narrative by omitting it. That’s why we love the Internet — it is our omniscient friend, ready to spill the secrets others aren’t willing to share. If the Internet lacks the information, we add it.
In the list of reasons for uneasiness with information filtering, my blogger identity ranks high as a contributing cause.
Developer documentation and transparency
Finally, I think working in developer documentation has slanted me toward transparency. Developers need to know the limits of a system, what is allowed or not allowed, because they’re building tools that depend on this knowledge.
If you can only call an API a certain number of times per minute, developers need to know this, as well as what happens if they exceed the rate limits.
In these scenarios, removing this information from the docs can be severely detrimental. For example, if a developer exceeds the rate limits on API calls, are they suddenly charged for every extra call, or will their application stop working, or will they be throttled? Developers need to know the limits so they don’t exceed them, because so many factors — the user experience, security, finance, etc. — depend on this.
So the gizmo lacks an adjustable timer? Okay, that means developers might need to implement their own timer, or figure out how to initiate actions without a timer. This may require extra development time and resources. It’s important to know the information up front to properly plan for release dates and project timing. Hiding information will only create enemies out of your users.
Developers also live in a culture where information is more freely shared in frank and honest ways. Developers foster the irreverent, free-speaking culture of the Internet (see Reddit if you haven’t discovered it yet). Hackers regularly expose secret information. The culture of sanitized marketing speak doesn’t work with the Internet generation, particularly among developers. Marketing is basically a cultural anti-pattern with developers.
In the reasons for my uneasiness with filtered information, I consider my focus on developer documentation also a strong factor.
Conclusion
I know I’m preaching to the choir about the importance of transparency. Almost no tech writer would champion information control and manipulation in any form or setting. But no doubt you’ve had a similar ethical scenario, where the plain-speaking words in your information-rich, helpful documentation were lassoed and hogtied by a product manager or marketer who didn’t want anything negative included in the product’s documentation.
How do you persuade these higher powers (who usually hold more clout and control) about the right strategies? Maybe we don’t have to. When the information does start to unfold online, through blog posts, forums, and other channels, perhaps a greater truth will be made plain. Those unencumbered by corporate strictures will be able to explain the product’s shortcomings and limitations with absolute cutting clarity for the rest of the world to understand and benefit from.
At the end of the day, we don’t need to get upset about whether we include or exclude information from the documentation. It will eventually be written, just probably not by us.
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.