How Handbooks Fill the Documentation Gap in an Ever-Changing Tech Environment
A Play in Two Parts
(scene)
Meet Claire, a new software developer at Lamentable Industries. Fresh out of school, it’s been a challenge adapting to a corporate environment. Finding her footing in her first real, grown-up job has been much harder than she anticipated.
To help ease the transition, Lamentable assigned her a mentor. Kevin’s a seasoned, grizzled veteran there, hired 14 months ago. Kevin almost even knows what he’s doing.
Claire’s currently working on an API that auto-fills TPS reports. It allows users to complete them 60% faster so they can free up their time for more satisfying endeavors, like watching kung fu movies.
Before long, Claire gets stuck trying to connect her API to their internal gateway. This is Claire’s first big work project and her panic escalates with each failed attempt. Her Impostor syndrome is starving, and her insecurities are like an all-you-can-eat buffet in the midst of her self-assured tech counterparts.
Claire combs through her team’s Confluence and Git repositories searching for instructions, but finds two completely outdated and contradictory answers. Claire moves on to Plan B and searches for “gateway connection” on the company’s intranet site. She gets buried in an avalanche of useless returns. She’d Google it, but the gateway is proprietary so she knows it would be a waste of time.
As a last resort, she works up the courage to ask Kevin. She’s greeted with an all-too-familiar heavy sigh and an aggrieved eye roll. “I’m slammed right now. See what you can find online, and if you can’t figure it out, grab some time on my calendar tomorrow and I’ll walk you through it.”
Dejected, Claire pulls up the #gameofthrones Slack channel and fantasizes about borrowing Needle. She spends the rest of the day daydreaming about all the pointy-end stabbing she’d like to inflict on Lamentable’s worthless documentation.
(/scene)
Any of that hit a little close to home?
It’s a Numbers Game
The math here is simple: there are 3.7 million open tech job postings according to cyberstates.org’s 2019 analytics report. There aren’t enough qualified applicants in the job pool, which is bad. Plus, the gap is growing due to the lack of skilled workers in the pipeline, which is extra bad. This, my friends, is what we call a supply and demand problem. And that pinch is being felt on both sides of the labor market paradigm.
Understaffed companies won’t be able to innovate fast enough to win in the marketplace. Allocating so many resources to hiring and training new workers only serves to make things that much harder. This matters because it’s not like the next generation of apps are just going to build themselves…Well, not until the AI and Machine Learning engineer shortage gets sorted out, at least…
On the labor side, overtaxed developers and engineers are fraying at the seams. According to data recently gathered by LinkedIn, software and internet companies had the highest levels of employee turnover of any major industry. That attrition adds up, too. Can you count on the engineer who wrote a mission-critical tool last month to be around 18 months later? Because that’s when the company’s next generation of engineers will need help with it.
Tribal knowledge no longer cuts it when the tribe expands and turns over at unprecedented rates. I can’t tell you how many times developers have told me accessibility and usability of information is their biggest pain point.
Job attrition combined with accelerating tech innovations are resulting in an information quagmire. More than ever, it’s increasingly difficult for developers to find the documentation they need. Information is strewn about in a variety of places and formats. Worse yet, it’s also often outdated, incomplete, or flat-out missing.
So how did we get here?
Technical communication documents aren’t exactly some sort of new-fangled idea. As a point of reference, divers once discovered an ancient Greek “user guide” that may date back to at least 50 BC! That guide instructed users on how to use a rudimentary, analogue computer. While technology has advanced in unimaginable ways over the last 2,000 years, technical documents haven’t always kept up.
These days, technical writers get paid to create more sophisticated software user guides. They generally contain some screenshots, diagrams, and step-by-step instructions. If you’re lucky, you’ll get a glossary and an FAQ section. And for quite a while, that was enough.
Until it wasn’t.
It’s no longer good enough to put together a user guide that instructs your developers how to do something. It’s more important than ever to have a single, definitive source of truth that explains the history and why. Capture that context before it walks out the door and disappears into the ether.
Offering a Helping Hand
Forward-thinking companies have begun applying a more modern approach to their technical documentation. Handbooks are replacing user guides as the definitive resource to build and deploy software by containing curated content and setting context. They also provide the latest information on tools, processes, and policy requirements. Best of all, they act as a centralized, single source of truth.
New methods, however, require new skills. Tech writers have to be willing and able to meet with senior leaders within the organization. Don’t embed yourself with some engineers to capture different processes and call it a day. You need to be able to document why it all matters. How does this software, policy or procedure fit in the bigger picture? Those answers come from meeting and interviewing the key decision makers.
Tech writers will also want to brush up on their influencing skills. Senior leadership has to declare handbooks as the go-to resource for the company. Otherwise you’re back to square one, as developers return to the wild west of unreliable Git, Confluence, and assorted crib sheets.
Modern documentation also requires a modern voice. Embrace the diversity of your audience and provide inclusive content. Use non-gendered nouns and pronouns, universal analogies, and accessible language. Non-native English speakers need to be able to consume your work.
As someone who writes handbooks for a living, I know how important it is to keep them accessible. My readers want answers, not entertainment. I save the pop culture references for blogs like these. Speaking of, let’s check back in on our protagonist from Act 1.
(scene)
After a grueling year at Lamentable Industries, Claire decides her watch has ended. She updates her availability settings on LinkedIn and the recruiter floodgates burst open.
Claire researches which companies care about making life easier for their software developers. In every interview, Claire insists on learning how they store their technical documentation. She certainly doesn’t want another Lamentable experience.
What do we say to missing and outdated information?
“Not today.”
Claire accepts an offer from Sunnydale Tech and finds greener grass on the other side of the tech fence. Sunnydale features an entire online library of handbooks that covers everything from their Software Delivery Life Cycle to their API design standards.
All the information Claire needs is accessible and at her fingertips. The well-crafted handbooks allow her the freedom and autonomy to work independently. She finds her confidence growing with each successful API deployment.
Feeling accomplished, Claire pulls up the Sunnydale #gameofthrones Slack channel. She breathes a sigh of contentment, finally understanding what’s west of Westeros.
(/scene)
You Get What You Pay For
If today’s technical writer role sounds like a lot, that’s because it is. Companies that strategically invest in their documentation earn a significant competitive advantage in return. Making work easier is a major driver in attracting and retaining software developers. You’re going to want to listen when they tell you accessibility and usability of information is a priority. Then go hire great tech writers to fix it.
DISCLOSURE STATEMENT: © 2019 Capital One. Opinions are those of the individual author. Unless noted otherwise in this post, Capital One is not affiliated with, nor endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are property of their respective owners.
