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


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.




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.


Back Off, Creep!


Image result for back off creep

Why do Technical Writers Care About Scope Creep?

Typically, Scope Creep is defined loosely as adding additional features or functionality to a new product, or adding unauthorized work to a project in progress, thus adding to the “scope” of the project that has already been defined – that is, adding to the “scope.” Adding functionality to software will, for example, add additional development hours and while it might make for a better overall product it will increase development time and cost, and it might even be more than the customer asked for or was expecting.

Imagine it this way – you hire a contractor to build you a lovely kitchen. You agree on cherry cabinetry with stainless-steel handles that have been ordered from a warehouse and you have provided the contractor with your drawings for how those should be installed and where. You like your design, and the contractor likes your design, so all is well. A deal is made to finish the installation of those cabinets in two weeks, complete with the hardware. Great. But then you discover these cool undermount lights that would make your countertops look extra cool, and all that needs to happen is that your contractor must drill holes in the back of each cabinet before

instkitchenallation so that the electrician can wire them seamlessly into your plans. This is a simple task, drilling a hole in each cabinet, and you have not asked the contractor to do any electrical installation whatsoever. But those holes must be measured precisely so that the wiring is exact – which takes time. And math. And a drill.

Scope creep.

Your lights will look great, though.

Your cabinetry will now take one and a half weeks to install. And it might cost a little extra.

How badly do you want those lights?

How much does the customer need that extra functionality in the software?

Now, on to why technical writers care.

Each time I have a project laid out in my Agile Calendar, I have planned a certain number of hours for each project. I know roughly how many hours it will take me to learn and understand a software feature, whether I will understand it based on what the developer hands me or if I will have questions about where it goes in the existing documentation set, whether I need to create hyperlinks, whether I need to talk to the QA team to see if that procedure needs testing, and whether I need to revise what the developer gave me to make the text more reader-friendly. I have to scope out not just whether that doc must be placed in one section of the manuals, but whether it should be cross-referenced, whether it should be noted in “New Features,” “Release Notes,” and so on. Do I make an announcement to customers? Do I have to provide notes in any other sections? The current online documentation that I curate would span over 6,000 pages if printed, so I am mindful not to repeat my writing in too many places, hoping to never have the doc reach 7,000 pages – just in case we ever print it!

This fact – that I have a planned set of hours – means that when a developer (or the team of developers) decides that the cabinets could use some really cool undermount lights, I have to readjust my calendar accordingly. I am, in this metaphor, the electrician who is about to find out that her small rewiring job is about to include 20 new lights to install. My calendar shifts quite a bit! When I start out thinking that I have 2 or three documentation changes with one or two hyperlinks and a sentence in the Release Notes, I wind up with a rewrite or an entirely new page, but should I complain? The customer ends up with cool undermount lights!

Well…scope creepers beware. Technical writers can bring about scope creep on a whole new level. Being mindful of a document’s goal, or a document set’s goal, is a big task. In the planning and execution stages, it is my job to make sure that each of the reader’s needs are addressed. When my team creeps, adding new functionality, I tend to creep even further, trying to make sure that my users get ALL of the information relevant to that new function. See where this is going? The developer adds detail, I add detail. It’s like getting a little crazy with the salt shaker.


So, fellow writers, here is my wisdom to you – do your darndest to work on the examples and the  metaphors and avoid the creep. Stall the creep at its root. Break your chunks into smaller chunks and help your developers and your project managers do the same. It’s totally fine to put in the undermount lights, but remind them that a whole new manual page needs to be written to tell users how to turn the lights on and off, how to operate the dimmer switch, and where the breaker is located.

Express early and often that if they want to add new functionality, they must write a new story. They should ask whether it is really a new feature. They should approach your time and expertise with more than “it’s a minor doc change/update/addition” each time they add a cool bell or whistle – or undermount light.

If the scope must get broader, we must return to the goal and reevaluate. Consider whether those lights are their own entity, or whether they can brighten up the whole room – or whether they will simply cast a creepy glow all over everything when you come to the kitchen for a glass of water in the middle of the night.moon




Risky Business



Risky Business – The pitfalls of users who truly don’t read the doc.

We’ve all been there. The daily task of looking at the comments section of our documentation to respond to users, only to discover a question or comment from a customer only to respond in frustration because he or she clearly did not read the precious words we’ve written. It’s obvious from the question asked, or the comment noted, because we’ve addressed the very issue just lines before, so crisply and clearly, they could not possibly have missed it.

How do we achieve that elusive goal- getting customers to comply? Why, oh why do customers ignore our hard work?

It turns out that customer compliance is a multilayered issue, and there is, as you would expect, no simple answer, but that doesn’t mean that it is out of reach. In order to get at the issue, you have to think of it much like an adventure I had when I was younger, though. Work with me on this:

I grew up in the center of a small town. My parents were professionals. I went away for a couple of weeks each summer to sleepaway camp and spent the bookend weekends with my Aunt Helen who lived on a working farm. When I was about 12 years old, on the first weekend, before camp started, we picked cherries and strawberries, canned some tomatoes, and I fed the chickens who pecked lazily in the field behind her house. I marveled at the acres of corn in tidy rows that would be ripe in a few weeks. I asked her the names of the hens.

“They don’t have names,” she said, “They give eggs a while, and then they’re food.”

So I nhensamed them. Bess, Mavis, Charlotte, Diana, Mary Ann, and so on. There were ten of them. They were cute, and they pecked near my feet. I could tell them apart based on color patterns and wattles. They each had unique personalities, even. I felt they deserved names. They were practically tame, after all.

In a couple of days, Aunt Helen drove me to camp, and I didn’t think much about her or the hens until I returned two weeks later to enjoy a couple more farm days before returning back to my parents and my hometown for the rest of the summer.

The problem was, three of the hens were gone. There were only two left – Charlotte and Bess. I looked for them in the yard, thinking they had hidden in the roost, or gone off to find shade. Of course they hadn’t. When I asked Aunt Helen, she matter-of-factly reminded me that they were food. My uncle John had wrung their necks, plucked them featherless, cut them up and wrapped them for freezing.

My expectations for the chickens and My Aunt Helen’s were vastly different. In other words, people don’t always behave or respond in the ways you expect them to. My Aunt had explained to me why the hens didn’t have names. I just didn’t follow directions very well. Lesson learned, feelings hurt.

Users are the same way, but when they don’t comply, sometimes it’s not just their feelings that are bruised.

There can be risks for the user in that users who fail to read or interpret the documentation fully are at risk of damaging the product (or, often themselves) through misuse or improper installation. And there are risks for their company or business because they will invariably head to the support department, resulting in higher costs, OR, as is the case in the primary example I used here, they will leave a time-consuming question or comment that could have been dodged had they merely read the doc.

So although there are lots of factors that can impact user compliance and reduce these risks, let’s dive into the top three that impact behavior and reduce risk:

Age. I work in mainframe software, so I am keenly aware of age. Usability pros are keenly aware of the link between age and reading patterns, especially when it comes to web-based content. Older users read more, and do not look to leave a page through clicking quite as often. Be aware, though, in design, that older users can miss imbedded links without other visual cues, so placing links below the original field (one page, no scrolling) can be a tricky thing. Think of page design as just that – like a newspaper, things that are placed “below the fold” are often viewed as less important if the target demographic is the 50+ group.

Next up is Education Level. Those with a greater education will stick to a greater focus in reading, where less educated page visitors will skip around looking for the graphic or link that takes them to the next step. This is a tricky design element, because pages get quickly busy, especially when graphics and diagrams are essential to the basic function of what you are trying to convey.

Industry. This is tough because software is different from science which is different from automotive (I could go on and on in the areas of tech doc, and we all know it). This is a terribly important factor, and yet it still ranks behind age and education. We are no longer “reading the manual” in page form, so we have to be slicker than that. But heavily-regulated industries like software and medicine require us to be vigilant in testing and certifying our documentation and also require lots of compliance with the voluminous doc we include. Be choosy in design, and this will help a lot.

What we know about what never works (or mostly doesn’t work)

Plenty of times, designers think that issuing a stern warning to “Read this!” Will make users more aware and thus they will read. That is simply not so. Telling people to read often makes no difference. If users are prepared to comply, they will. If they are planning to skip over or skim, your handy warning is not about to move them along.

Overusing warning signals, notes and other hazard signs does not seem to do the trick, either. UX designers have tried to put the visual equivalent of caution tape along the reader’s path, but to no avail. Even when users will experience a serious outcome like an outage or data loss, very rarely does a warning lead customers to be more wary. (Does this feel like it’s getting grim?)

Overuse of design elements like boxes or offsets also has little effect. Sometimes it is visually stunning, but it does not cause folks to read what is inside, alas.

So what do we do?

There IS hope, dear writer – there are proven methods to perk up your reader and get her to pay attention, I assure you. All is not lost.

The first and simplest is first and it is simple.

Lean doc. Lowest common denominator. Think about how easy it is to read a YA novel. If you haven’t done it, go flip through “The Hunger Games.” It’s not a bad story, seriously. The writing is pretty good. Or try “The Giver.” When writing is clean and written to a simpler audience, it goes by in a breeze. So do that. Give up on verbosity and passivity. Get things moving. Don’t write high; write low.

Layer things to keep it interesting. Ignore part of what I said in the previous paragraph and throw in something seriously challenging every now and then just to spice things up. Don’t complicate matters just for the sake of complication, mind you. And don’t write a 42-word sentence to prove anything to your high school English teacher. Just go ahead and write the processes for grown-ups in a naturally challenging way.

Test your work. Then test it again. Make sure that what you have written works. If you create a trusted setting and climate in your documentation, you will be trusted. Respond quickly and accurately to your clients when they do make those comments that clearly could have been solved by reading the doc and gently redirect their attention to the place in the paragraphs where you explained it. Do a little hand-holding so they can see the benefit of your well-crafted prose. I assure you, building that relationship is worth almost as much as your fine prose. When users can peek behind the curtain to see that the writer is there, pen-in-hand and really knows her stuff, it is like a miracle occurred. And it is a thing of beauty.

That is the moment when, like Tom Cruise in the movie, you can don your sunglasses and dance to whatever music you want – no one is watching and you have the best moves ever.

But unlike the character he plays in that ubiquitous film, your story ends much, much better.



Agility 2.0 – Drive the Doc


In the age of agile, companies and teams all over are integrating new documentation practices as best they can in a more streamlined, cooperative practice environment. Continuous delivery of software or an integrated delivery environment can be a challenge not just for software engineers, but certainly for technical communicators. Hey, it’s hard to write the doc before the software has been written, quality-tested and everyone has had a chance to kick the tires and take the thing out for a drive. But we try. In a perfect agile world, there could be a new feature or function of software release once a day! But can we really write and revise documentation every day? That seems unlikely, and probably unnecessary. We know that our users don’t relish reading the documentation, after all.

It is a practical chorus in my office: “Who reads the doc?”

I argue often that those who read the doc are experiencing a pain point, and that it is my job to ease that pain before it becomes excruciating. They are undergoing the pain of introduction, installation, or – and we hope this is not the case – they’ve hit trouble.

So sometimes, it is indeed true that perhaps the doc should be updated daily, with new screenshots, demos, integrations…who knows? If something changes fast in the world of software, don’t we want the documentation to keep up as well? I definitely do.

There are some great tools in the field to help with automation ottsf doc – At MadWorld, we got to see how Jenkins builds works with MadCap Flare to conduct an automatic publish (that is a dream of mine, believe me). I imagine the day when I can integrate development and documentation, but there are some days when that seems like a far-off dream. Should I be satisfied with just DITA? Of course not.


Having trouble picturing what I mean? Imagine this: I want to automate a document that provides the directions from my office to my home. I could write these directions, “Exit the parking lot by turning left onto Smith Street. At the stop sign, turn right onto Maple Avenue. Pcarmaproceed one-point-three miles to Mary Street. Turn left onto Mary Street,” and so on until I reach my destination. I would have produced an accurate document reflecting the journey from office to home. However, on a sunny Tuesday, I discover that there is construction on Mary Street. The construction will last a week or more, so the directions to my house have changed – at least in the short term. I have to change the document, and I have to change it today. If I could dictate the directions to a VUI as I drive, I could have a new document in moments. In fact, as soon as I pass the construction and reconnect to a spot where the route is the same as the old document, I could stop the modification. I could merge the first document with the new one, republish, and my work would be complete.

That is just one way to automate, but since I am using a model of doc change while driving, I like it! There are of course other models of doc change while developing, but this one is pretty cool. I’m not sure there is a whole lot of need for updated turn-by-turn printed directions, but it was an easy model. Now imagine if I could apply this to updated installation for software, or a new release model for medication or pharmacopeia. I can go on and on about the potential, but if it is “dictate and publish,” it’s game on. If my developers can help talk through the model, I can clean up text with an editor and have my truly agile production line – shazam!

Text-to-speech modeling and agility are at the edge. Automating publishing is there, too. It will be fun to watch the merge points. (Merge, get it?) Get in the car, and let’s see where the construction zones are.

It’s All About AI. The Data Told Me So.

AIA conversation with a (junior) colleague this morning started off with “How did you decide to reformat your Best Practices Guide?” and moved on to things like “But how did you know that you should be working in Artificial Intelligence and VUI for this search stuff? I mean, how do you know it will work?”

I couldn’t help but chuckle to myself.

“Rest assured,” I said. “Part of it is just that you know what you know.  Watch your customers. Rely on your gut. But more importantly, trust the data.” The response was something of a blank stare, which was telling.

All too often, tech writers – software writers especially it seems, although I do not have the requisite studies to support that claim – are too steeped in their actual products to reach out and engage in customer usage data, to mine engagement models and determine what their users want when it comes to their doc. They are focused on things, albeit important things, like grammar, standards, style guides, and so on. This leaves little time for customer engagement, so that falls to the bottom of the “to-do” list until an NPS score shows up and that score is abysmal. By that time, if the documentation set is large (like mine) it’s time for triage. But can the doc be saved? Maybe, maybe not.

If you’re lucky like I am, you work for a company that practices Agile or SAFe and you write doc in an environment that doesn’t shunt you to the end of the development line, so you can take a crack at fixing what’s broken. (If you don’t work for a rainbow-in-the-clouds company like mine, I suggest you dust off your resume and find one. They are super fun! But, I digress.)

Back to the colleague-conversation. Here’s how I knew to reformat the BP Guide that prompted the morning conversation:

I am working toward making all of my documentation consistent through the use of templating and accompanying videos. Why? Research.

toiletAccording to Forrester, 79% of customers would rather use self-service documentation than a human-assisted support channel. According to an Aspect CX survey, 33% said they would rather “clean a toilet” than wait for Support. Seriously? Clean a toilet? That means I need to have some very user-friendly, easily accessible documentation that is clear, concise, and usable. My customers do NOT want to head over to support. It makes them angry. It’s squicky. They have very strong feelings about making support calls. I am not going to send my customers to support. The Acquity group says that 72% of customers buy only from vendors that can find product (support and documentation) content online. I want my customers’ experience to be smooth and easy. Super slick.

In retail sales, we already know that the day your product is offered on Amazon is the day you are no longer relevant in the traditional market so it’s a good thing that my company sells software by subscription and not washers and dryers. Companies that do not offer subscription models or create a top-notch customer experience cease to be relevant in a very short span of time thanks to thanks to changing interfaces.

Image result for artificial intelligence

I’m working to make the current customer support channel a fully automatable target. Why? It is low-risk, high-reward, and the right technology can automate the customer support representative out of a job. That’s not cruel or awful; it’s exciting, and it opens new opportunities. Think about the channels for new positions, new functions that support engineers. If the people who used to take support cal


ls instead now focus on designing smart user decision trees based on context and process tasks as contextual language designers, it’s a win. If former support analysts are in new roles as Voice of the Customer (VoC) Analysts, think about the huge gains in customer insights because they have the distinct ability to make deep analyses into our most valuable business questions rather than tackling mundane how-to questions and daily fixes that are instead handled by the deep learning of a smart VUI. It’s not magic; it’s today. These two new job titles are just two of the AI-based fields that are conjured by Joe McKendrick in a recent Forbes article so I am not alone in this thinking by far.

His research thinking aligns with mine. And Gartner predicts that by 2020, AI will create more jobs than it eliminates.

So as I nest these Best Practices guides, as I create more integrated documentation, as I rely on both my gut and my data, I know where my documentation is headed, because I rely on data. I look to what my customers tell me. I dive into charts and graphs and points on scales. The information is there, and AI will tell me more than I ever dreamed of…if I listen closely and follow the learning path.





Simplifying Complexity

Sometimes when I think about that task – simplifying the complex – it sounds as easy as boiling the ocean. Other times it comes as naturally to me as making toast. (Since I don’t eat toast, or even own a toaster, perhaps I should take that as a sign. It is never easy to make complex things simple. Not even making toast.)

Image result for toast

Yet every day, what I do in my work is to take cumbersome, complex tasks and recreate them in the simplest possible terms. When a huge banking system has millions of transactions per day and must synthesize them into calculable terms…I create language that can handle that. When there is an installation process that takes hundreds of functions that need to be done in seconds, not hours, I write the tasks that do that in ways that humans can understand without advanced degrees. I take complex ideas and distill them for actual people.

Brunch-MimosasMany years ago, when I was a bridesmaid for a dear friend, we hosted a brunch for the bride just a few days before her big day. In sunny Edmond, OK, just outside of Oklahoma City, we gathered around floral arrangements and mimosas for a few final gifts and sentiments. One of the things we had arranged for my dear friend was a book of recipes – not an atypical gift for a young bride. However, she was not your average young homemaker. We knew her so well that the homemade book, a collection to which we had all contributed, was filled with precious advice like “Vegetable Soup: Open can. Pour into saucepan. Do not overheat, boil, or otherwise burn.” And another great one: “Swedish Meatballs: Drive to your local Ikea. Once there, find the café. All will be well.” And perhaps the best: “Breakfast in bed: Open Pop Tarts box. Remove items from foil wrapper. Return to bed. Serves two.”

This gift indeed made the complex simple. It did not, however, lead to a gourmet life for the newlyweds. Nor did it improve her cooking skills. Hopefully she took some cooking classes or they made lots of reservations. No matter, she eventually became a successful oncologist and he a high school biology teacher. No one starved.

chocolate chip

The kitchen is the perfect example of where good writing, clean instructions, are essential to making the complex simple. Baking is an intricate act of chemistry that, if not executed properly, can yield disastrous results. The chemical process involved in baking bread is a dance of molecules that defies the odds of nature, and yet displays the beautiful synergy of both science and art.

On the other hand, missteps in the kitchen can yield fantastic new gifts, too. Who can overlook the great story on any package of Nestle chocolate chips, telling the untrue tale of Ruth Graves Wakefield and her adventures in creating Toll House cookies? (I hate to break it to you, but they were not really a mistake. Ruth was not trying to create chocolate cookies. She meant to keep those little chocolate nuggets intact, after all.)

My point is that every chocolate chip cookie recipe has a slightly different taste based upon a simple change: the recipe. Making the complex recipe ingredients: let’s face it, there are frequently at least TEN ingredients in the cookie recipe – and their variants.

Think about the variants alone:

Salt or no salt (I’ve tried it both ways, to varying result)

The # of eggs can differ

Fat – this is butter vs margarine or shortening. The variations in recipes is astonishing

A leavening agent – typically baking powder, but sometimes baking soda

The amount of flour, also the kind of flour

Whether to cream all of the fats and liquids before adding the sugars

The ratio of fats to flours

The ratio of ingredients and mixing and cooking times

All this is to say that just when you thought a simple task – making a batch of chocolate chip cookies – was just that, a simple task, you forgot that a whole lot of design and consideration went into the planning of that document. Or did it? Probably not. Your mom or her mom wrote down the recipe and you either liked her cookies or you liked someone else’s mom’s cookies. (My daughter prefers her friend Evan’s mom’s cookies to mine, if I am honest. And this is a good thing, because I shun carbohydrates and sugars like they bear the plague upon my house, so I cannot be trusted to bake anyway. I send college care packages of kale chips and they are darn good!) But when mom was perfecting that recipe, writing down all of the tweaks and updates, she was user-testing and updating the technical document. She just didn’t know it.

Even the original plan – the measuring of ingredients and the testing of oven temperature and the execution of the recipe – all of that was fragile and technical and required patience and repetition. The information that first started out on a sheet of paper next to the oven had to be user-tested and rethought once or twice. Or five times. It’s just that no one labeled it “tech writing” before they put it on a recipe card.

So now, all of these years later, while I am plotting out the schema for decoupling a conversational AI documentation scenario, I hope you will bear with me. I think one of the primary questions I will look into this week is, “Alexa, what is the ideal number of chocolate chips to put into a single cookie?” While I am researching the pure voice interactions and trying to nail down the intents and utterances and the minute specifics of how we can integrate this practice into the fiber of our lives, remember, it all started with the desire to simplify – and to make a cookie. So I’ll begin with that question about how many chips.

Once I have that answer, I will report back to you on the salt or no salt question, and then I will move on to the perfect flour ratio, and we’ll move on from there.  Or maybe I will create the ultimate kale chip recipe for a college care package.




What to Do When Your Documentation Speaks… Literally



So. It’s just after the holidays, and a whole slew of people opened a new Amazon Echo or Google Home brought by a jolly elf as a gift. Now, they are rolling their eyes or scratching their foreheads over the responses they get from their supposedly smart home assistants, or (if they are like one of my office colleagues) they are claiming the thing is trash, but perhaps better, they are praising the heavens and enjoying the heck out of artificial intelligence and Voice-User-Interface. Hallelujah for converts!

Many along any point on that spectrum are wondering how the heck it could be so difficult to get that stuff right, and many of you, dear readers, are wondering what this has to do with the price of peas and technical writing.

Allow me.

innovationYou see, a few weeks ago, my development team here at my office had what we all an “innovation sprint.” That is where we get to blow off some steam and quit working on our traditional run of the mill development tasks and think, instead, about the kinds of things we would do if we didn’t have customer deadlines and goals. We get to open up our imaginations and play around a bit – so what we did was to imagine what would happen if we could get something like the Amazon Echo to talk to mainframe computers and therefore get mainframe computers to talk back to the Amazon Echo – the ultimate in automation processes, as it were. Now mind you, the entire team does not have to participate. This process is totally voluntary. Team members can catch up on overdue work or sketch out other projects that they may want to work on in the future. They can conceive of ways to make their workdays easier or to otherwise improve the customer experience, that sort of thing.

But I was sticking with the Echo. I did not think it would work, but I am a glutton for impossible tasks.

I was right, and we failed fast. Too many security issues, turns out. But what did work, and what tickled me to no end, was that it IS possible to ask the adorable Voice User Interface to search my well-crafted user documentation (a tome that would be some 6,000 pages if it were printed, mind you) for any string of words or numbers that you wish to find, and the marvelous Alexa can be taught to return results with alarming accuracy. Voila!

Just like Alexa can learn movie trivia or what time the bus will arrive at my stop, just like this model of artificial intelligence can archive my weekly grocery list and take on my daily calendar or read each day’s news from a variety of prescribed sources, this cylindrical wonder will root through those words upon words upon numbers and more words, and even acronyms and reveal the right answer time after time. Once we program her.


In addition to these innovation sprints, my company also supports a project called the Accelerator. Think “incubator” but with less risk. A gargantuan company helping to nurture fledgling startups. It’s pretty great. First there is a rigorous application process and proving ground, naturally, but once you’ve run the gauntlet, it’s quite the ride – a supported startup, if you will. And that is where I am headed, my Alexa by my side.

A technical writer’s dream, and maybe nightmare, all at once.

It seems I have opened an oyster of sorts.oyster

I found a path to documentation using VUIs, a search tool for the largest documentation set with which I have worked. And after all, the Alexa was named after the Library at Alexandria, so it stands to reason. I am pleased as punch. Let the innovation continue, and the documentation shall “speak” for itself.