A Guided Tour in Tech Writing

Photo by Luis Quintero on Unsplash

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…

Photo by Alex Rhee on Unsplash

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.

You got the “D”?

Photo by Mark Claus on Unsplash

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:

Do you got the “D”?

A Beginner’s Guide to Technical Writing

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.

Who needs an Editorial Calendar? You, that’s Who.

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.

Dear Writers, Please Fail to Succeed

I’ve been a little focused on failure as the path to success lately. I think it is because my daughter is graduating from college and my son is graduating from high school, both in the same year, and both are sharply focused on what to do next. They are hyper-focused on the need to succeed, and I am spending more and more time reassuring them that there is more than one path to success, more than one definition of success, more than one way to measure success.

Allow me to meander a bit. We’ll focus on writing in a moment.

My daughter is a talented singer. She attended Ithaca College for vocal performance. That college is no joke for vocalists. Throughout high school, she experienced measurable success, though she tried to achieve more. As a college senior, though, she had a tough time with graduate school auditions and didn’t gain admission to the schools she wanted – she saw this as failure. My son is an actor. He attends a performing arts high school, he has been in more plays and musicals -both amateur and professional- than will fit on a resume. He was invited to audition for some of the top college conservatory programs on the east coast, only to be turned down time after time. He, like his sister, saw this as failure. My heart broke for both of them, like any mother’s would. They work so hard. They are so well-trained and educated. What happened? There is no simple answer. But instead of looking backward, the only way to look is ahead. What comes next? A plan to succeed. How to turn those downturns into something valuable.

Both kids now have separate paths ahead. My daughter is focused on a year of training and working with vocal students, looking into vocal health and perhaps a conducting MFA in another year. My son accepted an offer from a great college in New York not for theatre, but for film. Once he shifted his view, a whole new picture emerged. Actors are in movies, after all.

So on to writing…

I’ve written plenty of documentation that misses the mark. I have to go back to it and rethink, rework the process until it hits. I read the work of Nobel Prize winners Daniel Kahneman and Amos Tversky, who articulated how important it is to feel insecure, to lose, to get things wrong. (I am far oversimplifying this but the gist is – you must fail.)

As people, to succeed, we have to embrace failure in order to succeed. Tech giant Jack Ma spoke at the World Economic Forum in 2018 about his failure when he applied for a job at KFC. 24 people applied for positions, 23 people were hired. He was not one. He applied to Harvard 10 times. He was not accepted. 10 times! Talk about really wanting something!  Failure hurts, indeed, but we learn from it. It’s normal and maybe we should see it as a little less detrimental and harmful if we can start to view it as part of our growth. (I still doubt that I would apply ten times, but…)

I recently read H. Jon Benjamin’s “Failure is an Option” while on a road trip. Seriously funny stuff, that book. Part memoir, part joke, the whole book had me in stitches. If the guy who blends Archer and Bob’s Burgers and landed in a big pot of wealthy can’t talk to you about failing, who else can? And he can write, too! As a writer, I respect that. I brought his thinking to my writing, and to my workplace. He may not be drafting technical manuals, but the point is still the same. You can reinvent text, yourself, your path, and your work. Failure IS an option. Just don’t flog yourself over it. Don’t make it a habit, unless you are a comedian, and then if you are, write a book about it and cash in on the whole life experience.

Henry Ford is thought to have said “failure is the opportunity to begin again, more intelligently.” And I’ve read that it took Dyson vacuums 5,127 prototypes in order to arrive at that amazing, ultra-successful 5,128th model that we are willing to pay a handsome fee for – all to have a great experience.

Workplaces that penalize failure wind up with low-talent, low-energy responsibility-shirkers. In technical writing, and in any kind of writing, it is taking a risk, being willing to innovate and develop new methods, new approaches, and new techniques that blazes a new path to truly dynamic customer experiences.

Our work is integral to our lives. Our successes are integral to our work. What we do defines who we are, whether that is our job, our home life, our sports or our pastimes. When there is opportunity in decision-making, there is risk and there is reward (unless there isn’t).

So, dear writers, break out the pen, not the safe pencil with the eraser, and make yourself uncomfortable. Mess it up. Then fix it. Then learn from it. Fail…to succeed.

The Data Story

I’ve mentioned before that I am something of a Data Nerd. This is unusual for someone who is also a “word artist,” but hey, a girl can wear more than one hat, can’t she? I’m also a mother, a triathlete, and a lover of Emily Dickinson’s poetry. In high school, no one would have pegged me as a future triathlete, and no one who knows me now would imagine that I was ever *not* an athlete, so there you have it: the Venn diagram of Susan.

At the heart of this is data. But data about just me is not all that interesting. Data about thousands of people, and especially customers – now that is interesting. Even better is this funky cool tool called “Google Trends.”

As a technical writer and UX Copy Writer, I find this handy-dandy tool super fun and useful. You may be asking why. I’ll tell ya.

With a heavy-lifter of a creation like this, I can sit back and think about trends and numbers in ways I used to have to do lots and lots of work to get at. Research is a UX/UI wonk’s best asset. If I understand what people like, what people do, what people are looking for – I am on top of the world! I can simply and easily take a look at what was, generally, trending in the United States in 2014:

Searches included World Cup, Ebola, Malaysia Airlines, and Flappy Bird. People wanted to know about Kim Novak, and Jared Leto, and the Paleo diet was all the rage. By 2018, folks were clicking to learn about how to apply magnetic lashes. The Paleo diet was gone, but the Keto diet was in. Mega Millions was a top search, along with Logan Paul and Megan Markle.

Peoples’ interests and learning curves mark what I need to know, and they show this in words. Words make their decisions, drive their purchases, and reveal their inner thoughts.

So why is all this information so important? Again, I’ll tell ya.

I like to know which words people choose, and why they choose them. Wouldn’t you like to know why I write this blog, and why I choose the topics I do? I choose the topics because something pops into my head, or creeps its way in after I think about it for a while, and it is something that has been trending, or poking away and needs (in my opinion) to be discussed. It has to do with tech writing, or aspects of technology, women, and writing, and therefore fits the general parameters of this forum. Follow? But then, also it has to interest me. So there is an overlap. That’s where the Venn diagram hits. My interests, crossing over with my expertise, crossing over with something that I think will appeal to YOU.

And then, I write about it. But without the data that I could gather from some nifty tool like Google Trends, where would I be? I’d have no idea that the latest trend, in May of 2019, is that there have been more than 100K searches for Theresa May, and more than 20K of those searches were in Canada. Neat, too, that over 5k Canadian folks searched today (5/24) for the results of the cricket match between Pakistan and Afghanistan, right? Again, why does this matter? Well, because I doubt that any reference in my design documents in the US that refer to cricket would conjure the sport as much as they would reference the insect. And while Theresa May is the top search in Canada, the movie “Aladdin” is the top search in the US, so that tells us a bit about what Americans are thinking this weekend, doesn’t it?

To tie this all back to data and words, I’ll keep it simple. The more we know about users, the more we know. This data isn’t spying, and it isn’t creepy. It is downright useful. As a UX designer and writer, as a technical writer, and as a strong customer advocate, it really, truly, sincerely is all information-based. Lots of times, people in my orbit who are not in the tech realm get a little freaked out about all of this information gathering. But I don’t. I like it a whole lot when I can use data – information – numbers – WORDS – to get me where I am going and get me what I need a lot faster.

Even better when I can deliver that to my users.

Namaste.

Making Meaning

Back when I was an undergrad (please do not stop and linger long enough to consider how long ago that was), and I declared that I would be an “English major,” that declaration struck fear in the hearts of many. It did so because to those not-so-intrepid folks, that meant I believed, in folly, that I could write the Great American Novel, or that I would be content living a life for a few years as a starving poet, only to eventually cave in and become a teacher. My mother was a high school English teacher. Her mother was a sixth grade English teacher. The path appeared to have been laid.

I, however, had no real intention of becoming a traditional high school English teacher. I did enjoy a stint for a two-year period as a “teaching artist” at a performing arts magnet school where I had the luxury of teaching creative nonfiction for two and a half hours each afternoon, but I seriously cannot put that in the same bucket as mapping out rubrics for Huckleberry Finn or Hamlet for ninth graders.

Instead, that time provided me with a fantastic foundation for my own writing, which I still do (you are reading some of it at this moment), and the luxury of my mornings free. It was a great time. It launched me into other cool projects, and I got to work with aspiring writers without ever having to get my teaching certificate. I’ll take that as a win.

I moved through writing positions, always knowing what those early doubters knew: people think writing is easy, until it isn’t.

It is only in fairly recent history that writers have dovetailed so well with users and designers. (I have another post about this, so take a look at some older posts and you’ll see my position on UX and writing – I was ahead of the curve!) User Experience, or UX, was for a while considered to be a design concept, not a language one. Few people thought that the words themselves contained meaning. Most believed that an arrow was just an arrow – it could point users to what they needed, and whether it contained text was of no importance. That is, we thought that it didn’t matter what the pop-up or tab had written on it, just that there was a pop-up or tab. It’s not until we had dozens of those tabs from which to choose that things got murky.

But those of us who focus on words intervened to disagree. We started to ask, would users rather “click” or “select?” Is it a “flyer” or a “flier?” Are we really going to have yet another discussion about “dropdown” versus “pulldown?” We absolutely are going to have that discussion. And our customers will be glad we did. That disruptive error message a user gets – if it isn’t too disruptive, a customer won’t give up on using the software we have so lovingly designed. So, while marketing copywriters are diligently working to bring us customers, if we as tech writers and UX writers ensure a smooth journey through the software, we can keep those customers around for a long, long time. They will have had meaningful interactions with our product and our interventions.

Let the marketers worry about conversion. Let the us, as UX and Tech writers, worry about facilitation.

One of the things I have enjoyed most about technical writing is just that – facilitation. I often say that a big part of my job is “smoothing out the pain points” for those who use my software. I joke that no one reads the doc, but that is not entirely true. They read the doc when they have a specific need. That need is at installation: when they are brand-new and want to ramp up fast. Or, they read it when they hit a trouble spot: they want a solution to a problem. But there is a whole lot of “doc” in the interim, and that doc is within the product itself – the entirety of the product design contains compelling microcopy (or sometimes the microcopy is the opposite of compelling, let’s be honest). Prioritizing the user journey not just visually, but textually, a good writer can work with a good designer, and hit the jackpot, so-to-speak.

Extremely good UX means an extremely satisfied customer. A customer whose needs are highlighted by thoughtful text is one who sees a compelling product, I assure you. I feel the same way about technical documentation. If the tech doc supports a well-crafted product, and supports it concisely, there is little need for a stressful support call. Not all software (or any other product, for that matter) can be so well designed that it needs no documentation whatsoever. What we must do as writers in all realms is to create an experience, from microcopy to large-scale content, that is smooth and clean. If we do that, we’ll have done our jobs well. We will have made not just copy, but meaning.

Let’s Talk About Creativity

 

It is an almost universal refrain

when I tell someone that I am a “Technical Writer for a Software Company.”

“Oh, so not exactly exciting work, huh?”

“That would bore me to tears.”

“I couldn’t stand that kind of mundane work.”

To which I roll my eyes with boredom. Come up with something better, people. Do you really think I voluntarily spend my days sweeping cobwebs from my brain? Do you think it is fair game to insult my vocation simply because you are not bright enough to comprehend what I do?

Apparently, yes.

I’ll correct the record. What I do, while at times highly technical, is also quite creative and enjoyable. And highly technical does not cancel out creative and enjoyable, by the way. I spend my days problem solving and inventing solutions to problems that make users’ lives easier, that attack pain points and smooth out issues. It’s pretty cool.

But I get it. If you are not the sort of person who smiles when reading about coding syntax, then working in software documentation seems drab. (The funny thing is, a technical writer is a veritable savior when you can’t figure out how to install your new printer or why the WiFi isn’t working, amirite?)

The truth is, many of us could benefit from greater creativity in the workplace, not just those of us in technical fields. Most of us thrive if given some measure of creativity, even those who do not define themselves as ‘creatives.’ (Just for the record, I do, in fact, label myself as a creative person, and find outlets for just those tendencies both at work and in my personal life. I recommend it!)

Companies who hope to get the most innovative ideas from their workforce are wise to consider ways to encourage creative productivity in the office. I’ve got a few ideas I’d like to share. We use these on my team, and if you try some (or all – go for it) let me know what works, and add a few more to the tab.

  1. Support risk-taking. Cultivate a culture where risk-taking is just fine. I’m not talking about dangerous risks, but rather innovation risks. Try out a new project, allow for innovation time. At my company, we have periodic “innovation sprints” and “hackathons” to encourage new ideas and projects. Some of the fruit of these sessions have proven wildly successful, and some…have not. The best part is that both results are okay.
  2. Offer flexibility in how to do the work. A really cool thing is when you let your workforce test out ways to do things. While Sharon might do everything by the book and find that to be a super-effective way to get to the finish line, Roger might discover a nifty way to hack that project and the next thing you know, not following protocol will become the new protocol because Roger can show that the new way is a great way. Part of this can be offering a better work-life balance, like maybe Roger really can work better at 5AM than 9AM, and he is super productive then, so in-office time is not a priority, or perhaps Roger is really great at coming up with ideas that he jots down in a notebook first, even though typical company policy is to use only email. Get Roger an Evernote smart notebook, and you are on your way to big ideas!
  3. Think about communal space for idea sharing, even if it is offsite. Recently, my team of tech writers and I learned that our local coffee shop was hosting a 3PM “happy hour” and we decided to take a team meeting at that shop. Best. Idea. Ever. We met for an hour over hot java and solved some documentation issues that we’d not been able to solve at our own desks just by moving our thinking to a new location for an hour. And as a bonus, we all had some delicious coffee and a location break! It isn’t always necessary to move spots, and this time the company didn’t even pay for our meeting. We just had to jog our brains a little bit.
  4. Have fun. It is difficult sometimes to forge a genuine camaraderie, but it is also necessary. Break down silos and make an effort to not just be colleagues, but to be collegial. Creating a convivial mood by generating laughter, enjoying the office, and promoting a fun space generates creativity. Spin up a slack channel where everyone can post pictures of their pets, and pets only. If someone on the team doesn’t have a pet, find a workaround, like an animated pet – (come on, this is a creativity post!) Let inspiration flow freely in channels of communication.
  5. Focus on moving the ball forward in a way that everyone will succeed. Look, I work in technical communication and still the thing I want most is to be successful while I enjoy my work. Understanding that success might not always be money, but might be getting out of the office to enjoy sunshine at lunch time, or it might be the trust to work on a new project, or it might be an office space with better light – any of these are indeed ways to foster my creativity and make my workplace more enjoyable and my work product higher-level.

What’s the upshot of that for my company?

Happier customers, greater return on that investment, better work and for them – a bigger bottom line.

I don’t try very hard to correct people who think my job is boring and don’t understand it. I merely tell them, “Actually, technical writing is pretty cool. Your debit card works because I understand the code behind it and write the installation manual, so I bet you are pretty glad I do my job, right?”

They typically shrug and laugh, which is good enough for me. Little do they know, I have a lot of fun thinking of synonyms for a good part of the day, I create animated installation videos, I write VUI, and I spend a good deal of time daydreaming about the best, most innovative ways to make life easy. All because creativity in the workplace is important to me – so let me know if you can make it important in your tech writing space, too.

 

Simplicity Is Not Just for Sewing Patterns

 

There used to be job security in system complexity. Now, if you are the person who can simplify the system, you are queen of the world. Today, information flows faster and faster, and it needs to.

math   I recall when my third-grade math teacher told us all, “You won’t always have a calculator at your fingertips, so you will need to learn how to figure out percentages in your head.” Oh, she was a sweetie, that Miss Thompson, but I whip out my iPhone to figure out the tip at the restaurant every single time. And when I am shopping and it’s 30% off? You better believe, I reach in my pocket. So the simplifier rules the game.

It used to be that if the system was complex, it needed repairing, and that kept the repair team in a job. Remember the commercials for that poor, sad, bored Maytag guy? The ones sold a lot of washers and dryers based on reliability alone? In a faster-moving tech world, simply apply that principle to simplicity. No one wants to head to the manual, or call support. As the old saying goes, “Keep it simple, stupid.”

What does this mean, exactly?

The lines are blurring between content and structure, for one thing. The softening of the structured boundary between text, video, and image is an important distinction. Immediately, “manuals” are not “manuals” and reference guides online must seamlessly integrate video with rapid download times so that users can see a diagram followed by a 30-second to one-minute video showing a process, installation or example of how to use the tool or software. The days of scrolling down or clicking into a new window should go the way of the dinosaur. Our new design process should embrace the idea that a caption is not even necessary. Users can come on the journey with us, if we incorporate the right UX design principles into the mix.

The next step we have to embrace is a confluence between social media, mobile capture, and the cloud. Even in high-security systems, we are cloud banking, handling millions of transactions per minute on our phones, keeping virtual wallets, and more. Opening and closing our locks and homes with our keyless entry and embracing IOT. Our documentation systems can do the same thing just as seamlessly if we integrate social media quickly and we are smart. Why any lag time?

The coin we should be trading in now is simplicity, not complexity. To make these systems complex will leave us standing by the

coin

side of the road, waiting for the bus, while the hyperloop passes by above us. The best and most effective CMS systems will be those that rapidly and transparently create single-source doc that makes use of some old-school cut and pasting, but brings it into digital asset management with rapid integration. So, whatever you do when you think about brining your doc into the new era, don’t listen to the tech dev guys who lean toward complex systems because their jobs have always depended upon it. Instead, lean forward to the intuitive systems folks and the cloud-dev UX designers. We are building better mousetraps. The kind that don’t reinvent the wheel in order to ensure that more wheels need to be built.

After all, I do indeed have that calculator in my pocket, Miss Thompson. I didn’t need to learn how to figure percentages. I just needed to embrace the technology 30- years ahead of us.

bus

 

 

Strong Tech Writing is Strong Design Thinking

I’ve written and talked before about the deep connection I see between UX (User Experience) and ID (Information Development) and yet sometimes I feel like the hamster in the ball, just running around for my own amusement while processes and concepts remain more or less the same.

hamster-ball-1 (1)

I get it, it’s hard to steer large organizations through what seems like a largely creative change with little ROI. And yet I see the returns as potentially huge. As technical writers, when we see the end user as our audience, we know that our writing improves dramatically – that is, when we don’t just see the end user as “installer” or “programmer,” but as “reader of this paragraph or chapter.”

When we think more about audience as consumer-user, we employ real design thinking. That is the moment we become UX-ers supreme. In “The Sciences of the Artificial,” Herbert Simon (insert humble-brag here about how I went to Carnegie Mellon and Simon had a profound career at my alma-mater), charted the first examples of design thinking. Those ideas persuade my processes today, and should inform yours.

First, define – define what you need to resolve, and for what audience. (See how the audience is included there?) You cannot resolve a problem for every audience in the same way, after all.

Second, research Examine the history of the problem at hand. What are the obstacles that prevented it from being solved already? Collect examples of prior solution attempts. Take note of supporters, critics, stakeholders. Talk to the end-users and gather their ideas. Then examine the industry so you can consider other thought leaders’ stances. The solution might be an amalgam that is in plain view.

Next, ideate. Once you know the needs of your users and their motivations, you can generate lots of ideas, and be sure not to judge any of them as frivolous or out-of-bounds. One conversation at a time, you can surface up solutions that are worth exploring.

After this, it’s time to prototype and expand on the ideas and begin to create drafts.

  • – does it sound like I’m talking more about design than text? Take a look back. All of these ideas can be laid out not just in text. Information, after all, might need to be distributed in visuals, charts, video, Voice-User-Interface, graphics… Keep talking with your team about deliverables. After all, someone decided that a Red Octagon was the best delivery mode for a STOP sign, right?

The fifth step is to Choose among the ideas you have and review your objective. Winnowing down ideas by removing both emotion and ownership of ideas is extremely difficult, but once you do it, the next parts are a breeze. Assure team members that there is room for growth all around, and that there is never a penalty for a tossed-out idea, but there is plenty of reward for work on an adopted idea – if we execute a great development, then it is a win-win-win.

At the sixth phase, implement! Create task descriptions if things need to be divided – chunking information or designing graphics, interfaces, scripting or video – that sort of thing. Now is the time to own tasks and divvy up the work. Execute on the best skills and ways of delivering. Then deliver.

The final, seventh part of Simon’s Design Thinking is to Learn. Get feedback from customers, determine if the original goals were met, discuss what could go better nest time, how to improve on the process, measure success, and collect that data so that the next round is better, smoother, and a premium experience.

There is simply no reason not to apply each of these to information development, and the transitions are seamless:

In a nutshell-

  • Audience
  • Research to understand
  • Brainstorm within boundaries
  • Create prototypes that are not limited to textual surfaces
  • Make good choices
  • Implement – execute on your work
  • Execute by strength
  • Learn!

And that, my friends, is Information Design that brings the greatest ROI – no more hamsters.