Otherwise known as “ditch the jargon already.”

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.

Especially if it is jargon.

Part of the Research Backpack

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.

Namaste.

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.

There Are Few Limits

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.

Namaste.

For a long time, I thought that content management should be an organic process. That is to say, when something needed to be written or re-written, I’d know it, because the project or task would manifest itself as a feature or project story through my Agile Development calendar or it would emerge through technical debt, and I’d address it. I could do content cleanup and I wouldn’t waste precious hours calendaring. I already spend time providing regular posts and I have a notes app where I jot ideas – I have plenty of them – so I can harvest things. I use Evernote to tack web pages for references to my writing, so for a long time I thought an editorial calendar was superfluous.

But…

When my writing came to more teamwork and content that impacted internal teams as well as tech, well then. Sharing platforms and thinking about notation on spreadsheets? Content planning became a science as much as an art. Into my world came the Editorial Calendar. I thought about what I might want to do in planning, not just on a whim.

An editorial calendar allows me to:

• Consider a production schedule that is more consistent
• Track social media
• Encourage collaboration, not just solo production
• Balance content for graphics, media, and formatting
• Be accountable, if only to myself
• Analyze posts for popularity and relevance
• Plan things seasonally, well in advance

There are so many resources for calendaring that it can be overwhelming at first, but it’s not too hard to winnow things down quickly. Curata has a sweet graphic of templates and their features.

But I tend to just use Google Sheets. (not my sample)

WordPress also has a Plug-in, but hey…we all find our groove, right?

So what should go in your calendar? Well, that is largely up to you, but the basics are the basics:

How much content – are you super sleek and it’s just a tweet a day? Maybe, but it might be a blog post or even a few articles, a column, maybe a book chapter? Maybe you are looking at weekly, monthly targets.

Personas – definitely scope out your targets

Producers – who writes your stuff, who is responsible for what: copy, editors, will your blogging team in-house handle it or do you outsource some? Do you have a team, or solo folks? Name names.

Frequency of delivery – not frequency of writing, but when does the copy move out the door

Last, be flexy – Remember, there are holidays, people take leave (even you) and stuff might need an edit pass, new research, something changes. There are dates and then there are deadlines. Look, if a date is immovable, put it in bold red. But otherwise, understand that quality is super important. Ideas sometimes get superseded by better ideas.

I recently wrote a memoir. It took more than 2 years. I am still looking for an agent. The book is finished, but no one is publishing it yet. That part is not on my calendar, but the to-do lists surrounding it are. They are not concrete, but pretty close. They are important but not firm. My publishing schedule is important, they are on my editorial calendar just like this post was on my calendar, but I had to look up some stuff.

There were some work dates that were also important that needed addressing before I could do my fact-checking for this, so those went in. But hey, look, this made the site. Cool! And you are reading it (you are, right?) so yay, me.

Go find an app, test it out and kick the tires.

Calendar some dates – put an editorial calendar on your calendar.