I often hammer away at this thought, but coming to the close of 2021 and heading into another year of technical writing, closing out the first year of a new decade, it seems like it’s time to revisit.
The KISS approach has worked in many other areas of life – Keep It Simple, Stupid.
It’s a bit like the slogan Bill Clinton used to keep in mind: It’s Always the Economy, Stupid. Not that any of us are stupid – quite the opposite, in fact. Many of us are so smart that we naturally assume that those reading our documentation are equally bright. While that may be the case, often our consumers are bright and talented in other areas. Alas.
In technical writing, a few factors drive change and demand a better strategy. We, as writers, call for more user-friendly tools in our writing. Along came Confluence and SharePoint, along came markup, we got to use DITA.
Our managers expected measurably consistent outcomes and cost control in the content we produced. End-users required more user-friendly content. The evolution continues.
Each of these demands is the consequence of expecting easy-to-use methods and tools. Technical writing, the product, is a tool for everyone. What used to be in the rare air is now at everyone’s fingertips in a highly mechanized world. We used to refer to a revolutionary “plain language” style of writing, and now it is merely dubbed “Simplified Technical English,” the demand for which keeps growing.
There is even a dictionary of Simplified Technical English, and it comes with its own acronym, STE, so it looks as if the trend is here to stay. This way of writing improves clarity and quality, but along with those improvements come some difficulties. Any time there is a standard, there are rules. Can we commit those rules to memory as we have grammar and our beloved Strunk & White? Likely, no.
Instead of rote memorization, we look to tools that incorporate STE for us – again, back to those easy-to -use methods to help us out. We want to lessen the cognitive burden, freeing up more so that we can understand the technologies about which we write. Microsoft helps every time it incorporates a spell- or grammar-check into Word, and Grammarly or Acrolinx are to our benefit, to be sure. All of us in the writing game have a love/hate relationship with authoring tools designed by developers, but until we hybridize our own talents, here we remain.
It is key to remember that a great deal of our output is targeted at an international reader. Adopting STE, or Plain Language, is truly beneficial when we localize content. While we should stay far, far away from idiom, trending toward casual writing is in our favor. Using STE as a guide, and truly standardizing our technical writing across all documentation in a given organization is the single best way to ensure that our technical content is to-notch all the way around.
It may seem as though I am beating the proverbial dead horse in this writing, except that end-of-year is precisely when companies are looking to evaluate the cost, quantity, and quality of content produced. Measuring will help improve overall performance and delivery, and will help create harmony among writers and consistency between texts. Why does that matter overall? Because the team that can write with one voice, and that voice is Plain Language, STE, will project to the end user that the company, and its products, are synchronized in performance and quality. And that, my friends, is the penultimate achievement of any writing team.
I should probably start with a primer on Cognitive Bias before accusing anyone of allowing such biases to impact their release-note writing. That’s only fair.
Photo courtesy of Ryan Hafey on Unsplash.
In a nutshell, Cognitive Biases are those thinking patterns that result from the quick mental errors we make when relying on our own brains’ memories to make decisions. These biases arise when our brains try to simplify our very complex worlds. There are a few types of cognitive bias, too, not just one. There’s Self-serving bias, Confirmation bias, anchoring bias, hindsight bias, inattentional bias, and a handful more. It gets pretty complex in our brains, and we’re just trying to sort things out.
These biases are unconscious, meaning we don’t intend to apply them, and yet we do. The good news is, we can take steps to learn new ways of thinking, so as not to mess things up too badly with all of this brain bias. Whew, right?
Now that we’ve established a basic taxonomy, let’s dive in to how cognitive bias may (or may not) be creeping in to things like your technical writing. It’s not just in your release notes; that was just clickbait. But sure, bias can permeate your release notes and nearly any other part of your documentation. (Probably not code snippets, but I won’t split hairs.)
Writers and designers must recognize their own biases so that they can leave them behind when planning. Acknowledging sets of biases helps to shelve the impulse to draft documentation that is shaped by what they already know, assets they bring to the table, or assumptions they make about experience levels.
Let’s start with Self-serving bias. How might this little bug creep its way in to your otherwise beautiful and purposeful prose?
This bias is essentially when we attribute success to our own skills, but failures to outside factors. In our writing, this can appear when we imply that by default, software malfunctions are based in user error. Rather than allowing for a host of other factors, often our writing recommends checklist items that are user-centric rather than system-focused. While it’s true that there are countless ways that users can mess up our well-designed interfaces, there are likewise plenty of points of failure in our programs. Time to ‘fess up.
Confirmation bias can be just as damaging, wherein as writers we craft and process information that merely reinforces what we already believe to be true. While this approach is largely unintended, it often ignores inconsistency in our own writing. We tend to read and review our own documentation as though it is error-free, both from a process perspective and a grammatical-syntactical one. That’s just illogical. And yet, we persist. The need for collaborative peer-review is huge, as even the very best, most detail-oriented writers will make a typo that remains uncaught by grammar software. Humans are the only substitute, and always will be.
We write anchoring bias into our documentation all too often. This bias causes us, frail humans that we are, to rely mostly on the first information we are given, despite follow-up clarification. If we read first that a release was created by a team of ten, but then later learn that it is being developed by a team of seven, we are impressed by the team of seven because they are doing exceptional work. Now, it may be the case that when the ten-member team was working on it, three of them had very little to do. Yet, we anchor our thinking in the number ten, and set our expectations accordingly.
The notion that we “knew it all along” is the primary component of hindsight bias. We didn’t actually know anything, but somehow, we had a hunch, and if the hunch works out, then we confirm the heck out of it and say we saw it coming.
This can happen all too often when we revise our technical writing, jumping to an outcome we “saw coming,” which causes us to edit, overlook, or wipe out steps on the path to getting there. We sometimes become so familiar with the peccadilloes of some processes that we only selectively choose what information to include, and that’s a problem.
Inattentional bias is also known as inattentional “blindness,” and it’s a real doozy when it comes to technical writing, believe it or not. It is the basic failure to notice something that is otherwise fully visible, because you’re too focused on the task at hand. Sound familiar? Indeed. Our writing can get all sorts of messed up when we write a process document, say an installation guide, and don’t pause to note things that can go wrong, exceptions to the rule, and any number of tiny things that can (and indeed might) occur along the way. What to do when an error message pops up? What if login credentials are missing? System timeout? Sure, there are plenty of opportunities for us to drop these into our doc, and many times we do, but I saved this for last because – this will not surprise anyone who knows me – in order to overcome this particular bias, all you need do is become best buddies with your QA person. Legit. I recommend kicking the proverbial tires of your software alongside your QA buddy to see how often you get a “flag on the play.” That will grab you by the lapels and wake you up from the inattention, for real.
Your users will thank you if you learn, acknowledge, and overcome these biases when you write. Is it easy? Not really. Is it necessary? I’d say so. As my Carnegie Mellon mentor told me more than once, and I’ve lived by these words for my whole career: “Nothing is impossible; it just takes time.”
Take time with your writing, and you’ll soon be bias-free.
Technical writers wear a lot of hats. That almost goes without saying. And yet, I said it. We are called upon to have “jack of all trades” qualities that stretch into the domains of information design, quality assurance and testing, marketing, and more. There are splashes of business analysis (oftentimes more than splashes), and creativity, lightweight programming, and definitely time management planning.
It takes a natural curiosity and desire to learn to be a successful tech writer, and anyone without significant attention to the details that matter won’t get far. Getting bogged down in minutiae and useless side-work won’t do you any good, but the meat and potatoes – the grammar and syntax, the user understanding – that is where the rubber meets the road.
This is why I call out the question. Are you a user advocate? If you don’t approach all your technical writing as a pathway to advocate for your reader, you are likely missing a great opportunity.
Start with Help Content. Everything from software applications to mobile phone instructions beg for a rich help content guide for users. Without a doubt, users come to the Help when they have a pain point. They are either brand-new, looking to get up and running, or they have hit a snag, and they want to get back at it. There’s no time to waste, so getting the Help right is crucial.
The only way to draft an exceptional Help Content section is to think like your reader, and advocate for her. “What would annoy me most? How can I fix that? What would make me happy? What is the simplest path forward?” When you answer these questions, you write good (even great) Help.
Process Modeling is another area where advocating for your users is what puts you over the top. Remember that there are users out there who thrive on the IKEA diagram style of directions for process, just a simple picture show-and-tell, but there are also those of us who totally cannot follow those drawings and are utterly lost from page one. To advocate for both sets of learning styles, a good tech writer will layer-in a smattering of both, covering the bases visually and linguistically with a seamless pairing.
If conveying information to users in a way that meets their needs means adding flow charts or tables, then model that process from end-to-end and put yourself in your user’s shoes. It works every time.
Rinse and Reuse is a motto I’ve lived by as a user advocate. Many writers and managers call this “single sourcing” but that is just a fancier way to say, “if you wrote it well the first time, don’t write it again.” Walk yourself through the user’s journey, and if there is another place to use your elegantly written prose, do that. Familiarity doesn’t breed contempt, it breeds comfort. A user feels heard and recognized when he sees the same comforting words again. He feels knowledgeable. Wise. Learned. So, rinse off your documentation, excerpt it, use it again. Either link back to the original or include a whole page. It’s comfy.
Design like a trainer. User advocacy in technical writing means, in large part, thinking like a teacher. We never want a reader to feel like we are being condescending of course, but we do want to be on the journey with him, teaching him as we go. Incorporating good text design, like a lesson plan, is absolute user advocacy. Good teachers seek to elevate their students to a new level of accomplishment, and good tech writers should seek the same outcome for their readers. Have you noticed how much friendlier installation and process documentation has become? There’s a reason for that. Just as teachers no longer scold kids with a ruler to the hand, tech writers have softened their approach as well. It’s about elevating the experience, not just imparting the information.
Do these fit well and match my outfit?
By and large, if you put yourself in your reader’s shoes and ask yourself, “Do these fit well and match my outfit?” then you have begun the advocacy path to technical writing. More simply put, write like your reader, and speak up for her. You’ll improve your product, your outcome, and you will, at the end of the day, be a much-improved technical writer.
Connected web services are the meat and potatoes of the application world today, and providers have to work hard to ensure use and adoption.
Developers are looking for APIs that are easy-to-learn and that perform as they expect them to. Well-written documentation do everything from educating users to attracting developers to start new projects with what you offer. But how do you accomplish that well-written documentation? It’s not as simple as a user manual used to be, but not as complex as designing a whole new website, either.
Technical writers and content strategists who understand the purpose and goal of excellent API documentation are few and far between (but growing!) so here are a few suggestions to ensure that the API doc you write is best-in-class.
Tell the story.
Tech doc gets a bad rap for being dry and merely focused on the functional. When you’re working to drive adoption of an API, it’s key to start with the story. Consider how adopters and users plan to interact with your software, what their goals are – also what your goals are for them, and how you want them to approach the tools.
A prime example of some pretty amazing API doc (according to developers who say so) is Twilio.
Twilio landing page
Just look at that thing of beauty. A Confluence-based setup, this doc offers the story right up front. What does it do? “Power its platform for communications.” Bingo. Then, for new users, “What is a REST API, anyway?” Super smart. This approach leaves very little to chance. And by using Confluence as the basis, that handy-dandy left nav is right there, just waiting to be accessed.
Your story doesn’t do much, though, unless you:
Offer a clear start.
Twilio gets this right again. See the first selection after “What is a REST API, anyway?” Right there.
Twilio API Documentation
Twilio offers a base-level explanation, followed by the opportunity to jump right in. Offering code snips, links to a trial account – it’s all right there, easy to spot for new adopters, potential clients, and even users who have been there before by offering the “Twilio Console.” It is so seamlessly integrated that it feels like you are already a client!
Design the architecture for humans.
Here’s where to avoid mechanical, dry, boring documentation. It’s reasonable to expect that lots of folks will interact with your product primarily at the documentation level. Why bore them here?
Twitter’s API doc nails this and then some.
Twitter API documentation
No one who happens upon this page will feel as though they are greeted with robotic, poorly-planned text. This is written for human consumers with real application goals. “Measure Tweet performance: Build a simple tool…” Naturally, everyone will be enticed by the simplicity. And offering a tutorial? Perfect. This is where developers can come to learn what they need and avoid fluff and jargon.
Don’t be anything less than all-inclusive.
It’s flummoxing to arrive at what you hope to be comprehensive documentation only to find that it isn’t! Document everything, document it thoroughly, and document it well. Look, if someone doesn’t need it, they won’t read the extra, but if it’s missing? That’s just deadly.
Look at how smoothly GitHub handles this:
GitHub API documentation sample
Again, a Confluence-based (or inspired, at least) instance, GitHub organizes everything but the kitchen sink in the list of guides in the navigation panel. All of a user’s questions are answered, or referenced, in that panel. Quick start guides? Check. Building / installation? Check. Each of those navigation titles heads to a page with more information, labeled and cross-tabbed. It’s dream doc.
Highlight learning opportunities.
Never miss a chance to teach. Never. The more your users know and understand, the better you are and the fewer help requests you’ll field. Back to Twilio for an excellent sample:
Twilio API documentation
Products: API docs, quickstarts, and tutorials. All right there in the left nav, with a nicely-organized set of tools to learn. Sweet. It would be virtually impossible for someone to NOT find what they need to learn here. Chances are good that by offering both Quick Start guides and tutorials, all that a developer needs to ramp up is right there for the taking.
And finally, perhaps the most important of all:
Update everything, all the time.
Keeping doc up-to-date is a challenge, I know. Resources are stretched thin, writers work on multiple platforms and products. It’s the same old story. But here’s the thing: if your doc is out of date, then the perception is that your product is as well. The literal only way to ensure adoption and use is to stay on top of the docs. Even if you are sure that users are only reading 1/3 of them, it’s still imperative to head back in and troubleshoot, revise, and update consistently.
If you want people to adopt, you must update.
(I think I’ll use that as my next motto!)
Happy API Writing, fellow tech writers. Do it well, and you’ll rarely be thanked. But do it poorly, and you will suffer great pain.
I wish you well on your API journey. It’s sure to take you far.
I studied writing at Carnegie Mellon University (well, I first studied it in high school and had a teacher who was practically the grand master of Strunk and White, but I’ll get to that later). At CMU, we were indoctrinated into the Erwin Steinberg methodology of Plain Language. Today, that may seem like a simple concept, but I assure you, it wasn’t always that way.
Dr. Steinberg was something of a visionary. There was a time when most, if not all, technical writing was to be drafted in passive voice. It should sound authoritative. Certain. Unfriendly. Passive was the way to go! Professional and technical writing was horrifyingly boring, and that is just the way everyone seemed to like it.
Except they didn’t like it.
Imagine having to read this all day:
“The program will be completed by users only after the messages are received. Emails that have been sent will not be opened upon receipt.”
Are you asleep? I know I am. It’s just awful. And that isn’t even an example full of jargon. Wait for this one:
“Users should redirect their interface from the AWS blockchain system and consider a CMS that works with the UI. It can be discussed in scrum whether the vector graphics will be wired in or whether that is a sandbox item.”
Yeesh. I’m not even sure that makes sense, because I just tossed in all of the jargon that popped into my head. But I assure you, I’ve heard plenty of conversations using that word-spaghetti.
Jargon causes a problem no matter what, because using it runs the risk that your reader won’t understand it. Even seasoned readers don’t know all of the potential terms.
So Erwin Steinberg’s philosophy, the one that he impressed upon the hundreds of students he taught, and the philosophy of legends at Carnegie Mellon was this: write it in plain language.
Presto!
Whether the text you are creating is something you understand quite well or it’s something you are translating for an SME (see what I did there?) – Subject Matter Expert, try to be sure that you simplify. This is not to say that every piece of writing needs to be watered-down. Of course not.
Consider the uses of jargon, and the need for explanation. Moreover, consider the origin. Journalist Allison Linn, writing for the Associated Press, discussed the emergence of the word “solution” in the tech industry. In common parlance, a solution is that which solves something. Easy enough, yes? But in technical jargon, a “solution” is merely a product. Tech companies release solutions.
Marketing took over and created jargon. Along came words like “enterprise,” “experience,” “agility,” “migration,” and a host of others. We now optimize things, we migrate data, and…gasp, we coined the portmanteau “blog” from Web and log, and you have this little project of mine right here.
The difficulty with jargon is that it is used by a subset of people, not the whole group of potential readers.
What Steinberg taught was that messaging, even technical documentation, needed to be accessible. Writers should identify their audiences and write to those. So of course, if the consumers of a given piece of documentation are solely, exclusively tech-familiar end users, and those users will understand the acronym SaaS, then by all means go ahead and toss it in. But by and large, if there is a snowball’s chance that any Tom, Dick, or Mary will get their eyes on the doc, then just write Software as a Service, and follow up with the acronym, willya?
There’s no need to dress up the text. And here’s where my high school English teacher comes in. He loved Strunk and White so much that his mantra was “Omit needless words.” That guy would legitimately write it on every piece of nonfiction prose any student submitted. He taught me the economy of words. He taught me a grave distaste for the word “nice,” demonstrating that it conveyed nothing of value.
Nothing, he said, was “nice.” It could be splendid, lovely, beautiful, tasty, delightful, mediocre, incredible, and a host of other words, but it could not be “nice.” I miss that guy.
The last word on this subject is: edit. Supposedly, (and I scoff at this, but I am pessimistic), Mozart wrote a symphony in a single draft. We are not Mozart. Cut the chaff. Weed out the unnecessary.
I am really (truly) not a fan of those posts that apologize for when writers take a break from their blog and then assure readers that they will do better, be more faithful, write more – you know the drill.
And yet, here I am, apologizing for a lengthy absence. As if I have any readers left here.
The story goes that I moved from Pittsburgh (my bio still says I live there), and started a new job. That job was cool and it kept me busy, and I thought maybe I would just table the whole tech writing thing. I wasn’t really engaging in tech writing any more, so it made sense.
So, I left this little project alone.
Then, COVID-19 came along and I got laid off. Yeah, bummer, right? I focused more on my writing over at Medium (you can follow me there if you’d like, but it’s vastly different writing than it is here). I took some time to finish my as-yet-unpublished book. I’m still looking for an agent and publisher for that gem.
But after I got a new job, I was in proposal writing. Tech writing-adjacent. Sure, I edited and oversaw proposals in my tech life, but I started as a proposals manager for a small shop. Then I moved on to what I thought was a plum gig working for a friend at the company that brought me to Baltimore, then laid me off. Turns out that wasn’t the best gig, because they were undergoing lots of change.
And now, here I am, a proposal manager, but thanks to some strained workplace relationships, I am not really managing a lot of proposals, but I’m editing, moving things around, and digging in to some other work.
I’m hoping to leverage my smarts and talents to stay here and dig in to Confluence management and shoring up their much needed information architecture, but in the meantime, I will dust off my tech chops and head back to this comfy place.
All two or three readers, and anyone new who stumbles here will be treated to some new insights, a fresh look at how writing about technology dovetails with writing technical services proposals. I can’t give away any trade secrets, of course, or they wouldn’t be secrets. But all in all, I think I still have some good writing to share on this, my professional space instead of over at Medium, my personal platform.
So thanks for letting me take a break, and allowing me space to grow. Go grab a pint and let’s see what happens next.
More exciting than you think. Unless you are already a technical writer, and in that case you were already excited by the idea. Integrated Technical Writing is what folks who decided to call themselves “Content Strategists” have been yearning for all these years.
Yes, I’ve been known to lament that pretty much anyone can slap that label on and prance about calling themselves a content strategist, and it’s true. But if you can find a company whose position is fair and realistic, then integrating content and communication really is that strategy. And it’s fantastic.
I am with a company now, writing proposals for contracts with the government, local, state, and federal, and we GET IT. We totally get it.
I have embraced technical, marketing, and promotional collateral in such a way that I legitimately just put a woman in a sweet yoga pose on the front page of a proposal for the Department of Information Technology for the state where I work. Yes, indeedy. And the tag line is: “She’s flexible, but our standards aren’t.” It’s amazing. And we are going to win a $30 million contract as a result.
We are going to win it because our technical expertise is incredible, yes, but also because we wrote a top-notch proposal that sings marketing through and through.
Integrated Technical Communications has the key language built in:
It integrates the technical componentry with the Communication that needs to be done to sell. And selling is everything. If you cannot learn to operate the machine, the machine is useless.
The US Department of Labor Statistics will tell you how valuable technical writers are. Now go show the labor pool how valuable your creativity is in doing it.
Sharpen your pencil. Your black or yellow or blue or green pencil. Your integrated pencil. Learn the 5 Ws of online help. Learn the tools of the trade and some design principles. But importantly, learn how they all fit together and have fun blending and blending.
Integration is not just for populations and it isn’t a battle, that’s for sure.
It’s logical and it works, and NOW you can be a content strategist.
As writer’s, we’ve all got a toolbox or backpack full of our favorite things to use when we need to get a doc written, whether it’s a manual, proposal, or just a user guide. One of my personal favorites is a “Guided Tour,” because it involves asking a user who is able to articulate her needs, working with her to finesse the points, and then heading off to work my magic.
A Guided Tour is more than an interview, but less than a deep dive. It can be a simple phone call where we dash off some bullet points, but typically it provides some really great insight into what the document or website should look and feel like. As a hands-on, personable writer, this is usually something that, for me, saves a lot of work down the road.
How do you conduct a Guided Tour?
To begin the tour, it’s really a conversation with “muscle.” Ask the participant (sometimes there will be more than one, so I suggest having these tours one at a time) to give you a tour of their “space” as a concept. No, really. A walk through. You can do this physically with metaphors like:
“Imagine that your document or website is a house. What is the most important room, like the kitchen? Where does everyone end up at the party, despite the fact that you thought they would all be in the living room? Tell me about that most important place? Or, “When everyone arrives at your (document, website) what is the very first thing you want them to see? Is it the fireplace, the bookcase filled with your impressive reading list, the kids’ trophies from track? What really matters?”
Or, try a more exact approach:
“If you are walking through the aisles of the grocery store and you very much want to get just item X (the one you are designing for as priority), let’s talk about the things your readers will see before they get there – the user guide, the table of contents, the FAQ…and why.
You can talk through where the product is stored and how. You can discuss whether there are video links and archives, whether users are taken to other environments like sales and marketing and whether that is okay or distracting.
I often use imagery like organizing kitchens and garages because they are simple to visualize and valuable visually.
Identify Customizable Environments
Everyone’s product, like their house, is unique. We sometimes think that plug and play really means that, and that we are “stuck” within templates. We are not. Even minor changes will strike fear into participants, but if you are listening on your Guided Tour, you will find that they have customized an environment with their own acronyms, business terms, and priorities.
Asking a participant to guide you through their use of an application, even if it seems like it would be a strict template, can give you amazing insights. A good example is a Guided Tour through using the bells and whistles in their car. Just when you think just about everything is the same, you learn that there are some fantastic differences, and as a designer you learn that there are cool things that users wish they had that you could easily accommodate – and that, my friends, is where the magic happens! So use your observation skills, your enormous brain, and your determination to make that magic.
Deliver the goods
All of this is of course oversimplified for a blog post, but I know everyone who reads my brilliant prose is clever enough to extrapolate how it’s done.
Ask a participant to walk you through their reality and their wish list. Pay attention to how they dress up their product, their application, and their home environment. You will learn more than you thought possible about not only how they use what they have, but what they wish they could add to it – and you will likely find that you can help them alleviate that pain. You’ll be their hero when you can deliver that solution. (Trust me, gang, I’ve done it more than once!)
Write the architecture, organize the structure, and deliver the new wireframe or design. Often, the biggest roadblock is getting started.
Did you ever open the garage door on a sunny Saturday afternoon, having decided that today is the day you are going to finally clean that sucker out, get it all organized and be able to park your SUV in there at last? Sure you have! But then you realize that your daughter’s ice skates from her single 1982 figure skating season are in there, along with your husband’s college t-shirt collection because you once had a neighbor who made quilts out of those, and you agreed to store your mother in law’s dog crate. Besides, the holiday decorations still need to be taken to the thrift donation place, and…
I digress. You have to buy shelves and bins, and that is a lot to take on in one day. There’s a better way to – start. Maybe have a Guided Tour with the participants? Get an idea of how to use the space. Conduct this exercise with your users and determine where to house the skates, whether to hire the quilt lady, and so on.
Once you harness how everyone applies it, you will have drafted the shelves, and you can build an excellent user guide to the garage. A dazzling application, thrilling API for searching sports equipment in garage 2.0.
No matter what size your company is, or how well-known, I can assure you, every opportunity grasped or missed is the direct, straight-line result of a decision made or a decision delayed.
At lots of companies, decisions get stuck in a pipeline of waiting, approval, hemming and hawing, and sometimes they just die on a vine of withering that is just plain sad to see. Call it bureaucracy, call it checks and balances, call it whatever you like, but it is the companies that are agile, that pivot quickly (stop me if I venture too far into buzz words here, but they caught on for a reason) that survive and even thrive to defeat the others.
Making good decisions, and making them quickly, are the shining coins of successful businesses.
So why is a tech writer posting anything about them? I thought you’d never ask! You see, technical writing has ventured into the deep, lush forest of what now has the lovely, shiny name of “Product Operations” at some of those agile, savvy businesses. Those smart folks took a look around and figured out that the smart folks typing away were…wait for it…learning.
Yes, indeed. And they were right.
We writers have been busy doing, you guessed it, reading. We actually read the stuff we write, believe it or not, and some of it seeps in and we understand it. So when it came time to clear the bottlenecks of business, it sort of made sense to turn to the technical writers who’ve been sitting there reading and writing everything from user guides to employee handbooks all these years and ask them for some insight.
Some of us agreed to offer an opinion or two, and Product Operations was born.
One of the repeated mantras, week in and week out, that I offered to my teams in this process was:
If you oppose, you must propose.
Yep – learn it, commit it to memory. Take it to your teams. Feel free to swipe it. I think I stole it from someone else, and I’m not giving them credit here, so you don’t even have to say you nicked it from me, you can just take it and use it and hog all the credit. (See if it gets you a bit of a promotion or a raise. That’d be nice.)
What it means is, you can point out where something goes wrong – a process, a system, a way of doing things. Go ahead and say it doesn’t work. But then – you have to pony up a way to fix it. We may not use that way, but we won’t ditch it right out of the gate. The most important thing is, you can’t just complain. If you don’t have some sort of solution in mind, even a solution that, in the end, doesn’t fit, you have to keep your trap shut. Don’t point out the flaw until you’ve conjured up a workaround. Even a bad workaround.
A less-than-great decision executed quickly is usually better than no decision executed, or a good decision executed slowly. I mean, a bad decision is going to be a bad decision no matter what. But if you have a brilliant idea but it takes you five years to execute on it, do you really think it was worth it? You can tweak and modify as you go if you just get out of the gate. This is not cutting your bangs we’re talking about here, and even if it was, they’ll grow back. Usually we are talking about developing a new software program or implementing meeting-free Tuesdays. Start building Rome right away. By the time you get the blueprints made, you’ll find the perfect bricklayer, I assure you.
Start mixing mortar.
Right there, that’s the trick. Pick up a stick, or a shovel, or whatever the implement is, and choose. It’s just mortar. You can’t stir it once it dries. So, begin making decisions on a small scale in order to bring about success. As my grandmother once told me, everything can be fixed except death.
I think she might have been exaggerating a bit, so I don’t take it quite that far, but I have determined as a writer that until I hit “send” or “publish,” that I can just decide to write, I can move words around, I can float ideas and concepts, and that to do so is never bad.
In the mode of Product Operations, I started looking at things like information architecture, content strategy, and the blend of systems as a necessary way to get decisions made.
Lo and behold, it worked.
My team began to look at the gaps in our processes and realized that although we each knew what to do when there was a software outage, we each knew what to do when we had to deliver “less than positive” news to a partner or affiliate, we had never concretized that anywhere. So, off we went to create an “Incident Management Guide.”
Similarly, although we had our system down cold for how to manage time and processes in-house, we realized that if a significant part of our team left by, say, taking new opportunities with other companies, the knowledge vacuum would be fierce. The amount of just “stuff” we carried around in our brains about the day-to-day that kept the job pleasant and smooth was astonishing. So we set out to make it a thing. This was despite our tendency as a crew to just be renegade in our approach to daily office behavior, where a meeting was just as likely to be over coffee as it was to be in a conference room. Suddenly, processes and procedures were born.
Some decisions matter, some don’t.
All of this is to say, throughout my years (and they are numerous) I have found that there’s a certain transition from small operation to large, from laid back attitude to not, and back again, that says you somehow gotta put some stuff in writing even when you are pretty sure you don’t. It just makes life easier when you deputize people to have The “D” and to turnaround that decision more easily because they know they can. To build a team with that mojo because it says in a manual (online or in print, with chill or without – you do you) that they can. We built a very nifty team of people, and then we were really able to get stuff done on a big scale by saying, “here’s how we get stuff done.”
I’m just pointing out that it makes life easier if you know:
Okay, so I admit I put this aside for nearly a whole year because I thought I wasn’t really going to speak much to the topic any more. I shifted my focus into Product Operations with a cool company. I moved from one city to another. My youngest graduated from high school and I was on to other projects. I finished a book and started looking for agents. Frankly, I was too cool for school and I thought maybe I would just let this thing go the way of the dinosaur and that was okay by me.
Product Ops was, in a way, a bit cooler than Doc Ops anyway, and I thought I didn’t have time to focus on tech writing. To be fair, my new job was taking up a whole bunch of my time. (I know, that is a whole laundry list of excuses, right there.) I forgot that I actually enjoy tech writing and all that comes with it, and I had no crystal ball that would tell me that in the wake of a pesky little virus, my company would see Product Operations as, well…expendable.
So I am in my home office, a cozy little spot, thinking again about the demand for technical writers, and surmising that there is indeed a demand in the increase for technical products, and that even as the curve begins to flatten out, we’ll see an uptick in the need for folks like me (and presumably you) to explain all of this stuff to laypersons.
According to Venturebeat, Zoom, the online meeting tool that allows users to hear and see their meeting mates in realtime, daily users “ballooned” from 10 million to 200 million in April alone.
Talk about a tech explosion, and that is a simple use-case. The users in that example are an average group – teachers, friends, regular Joe offices. These are not high-tech examples, and the technology behind Zoom was already in place, no major infrastructure had to be spun up. So…yeah…
If we try to imagine the future just a little bit, and we know from previous models that any time there is a world-changing event (think 911), things will most certainly not go back to they way they were, we will see a host of new changes, new technologies emerging.
Want an example?
Let’s stick with 911 – after that horrific event, we had the need for new scanning devices at every airport in America. All of those came with installation manuals and both digital and print guides. Tech writers. We had body imaging tools – tech manuals. We had risk mitigation manuals – tech writers. We had procedurals, process manuals, new technical guides on airplanes, FAA guides, you name it. A veritable cornucopia of writing.
In the wake of this virus, the same will happen. There are protocols, articles, tools, procedures, styles, guidelines, materials, but there is software, hardware, programs, – you get where I am going.
So how does all of this matter to the new technical writer? Why did I title this piece “A Beginner’s Guide to Technical Writing?” I did not just have a fit of memory loss.
Growing Demand
Employment growth in this field will exceed estimates due to continuing increases in products and procedures. It simply has to.
Technical writers have to be lifelong learners. If you happen to be the kind of person who has ever said, “Wow, I wish I could just go to school for the rest of my life.” I suggest you might want to be a tech writer. I get to learn stuff every day. It’s pretty sweet. I have the pleasure of learning, teaching, writing, disseminating. And I learn about really cool things.
Okay, if you are all, “But I don’t want to write about software. Yawn” I hear that. I mean, software makes my heart go pitter-pat, but if that isn’t your jam, I get it. But hear this: technical writing gets into transportation, energy, television, academia, publishing, and…yeah, health (wasn’t I just talking about viruses?). So if you are all scienc-ey, or if you’re all about jets or planes or something, get in there.
It’s also about planning. If you don’t fancy yourself the kind of person who can just sit down and write about a topic, that’s fine. I am never that person. I have note cards or post-its, or now I have files in my computer, y’know, fancy programs and roadmaps, but you do you. I plan stuff. I plan it quickly now that I am a grown up, but still. It’s not unlike a semester where I had fifteen weeks to think through a project and execute on it. Project planning is a key thing. I am half project manager and half writer. I know my stuff before I pull out the keyboard, and what I don’t know – I learn. Woot!
It’s Partly UX, Which Is Super Fun.
I already have too many (is there such a thing as too many?) degrees, but if I didn’t I’d go back and get another one in UX. A big part of this career is user testing, user interface. Man, is it fun. You get to figure out how the people who interact with what you write actually use what you write, and whether or not you did it well. Does the reader understand what you said and follow the directions? Did they miss a step? Did you anticipate their initial reactions and questions, or are you so familiar with the product/concept/tooling that you missed it? It’s like a game where you play it out before you write and determine who they are, what they need, where they will be when they read, why they are reading it in the first place, how they will read it (on a phone, on a tablet, in a car…), why they will read it (is something broken, are they installing, is there a question), when they will read it (are they at work, did they just open the box)…and it’s like a choose-your-own-adventure book. You can create maps and endings based on various outcomes, except you have to be careful because if you create too many variable endings you’ll have a 5,000 page user manual and that is ludicrous!
You Are a Mapmaker
Just like planning various endings, you create treasure maps. You can create wireframes for websites, but you can do this with words, with tables of contents, with document maps. Learn to do it well, and you will be great at your job, and people will come to you for advice. At my company, I always felt great when colleagues came to me to ask where they should house documents, where it seemed “right” to put new information.
I often talked with teams about how Information Architecture was a lot like organizing a brand-new house. If you go into a housing development, many of the houses have the same footprint, or similar. The kitchens are “kind of” the same, but each one will be organized a little differently. You can bet that in them, if you look, the glasses are kept in one cupboard, and the plates in another; you won’t find things strewn all over.
But each kitchen will have its own personality. Its own flavor.
The garages, though? Oh dear. Those houses, and those garages. They are probably a storm of a mess.
So what I do is come in and provide some structure for those garages. I provide organization, shelves and bins and labels to all of that information. That is a great part of being a technical writer. The organization of all of those words and labels and ideas. You make the map of all of the information, sometimes in small chunks, and sometimes for the whole organization.
Start Out
If all of this seems like a lot, and perhaps a bit disjointed, welcome to the life of a technical writer. If all of this seems like fun and intriguing, and like a cool way to spend your day, welcome to the life of a technical writer.
Start trolling LinkedIn for some entry level positions because there will continue to be a tech-driven economy, and a need for more people who are willing to understand the language to explain the code and the machinery and the science.
If that’s you, and yet you enjoy the writing and the grammar and the syntax, the next 20 years are yours.
Have a Pint at the Tech Pub 