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.

Neural-Network-640x360

 

 

 

Strategically Named

 

letterpress

So very often I hear about how tech writing is a dying industry, and it makes me sad. Then, I remember that our name has just changed. The bluster is just bluster. We are content managers, information engineers, media strategists, and so on. The funny thing about some of this rebranding is, I recently looked on Glassdoor, and learned that, depending on what you call yourself, the salary for those titles varies widely.

For example, the average “media strategist” nationally is clocking in at $46,736, while the national average for a “content strategist” $70,000. I’m wondering what the huge distinction is, to be honest. And, I can admit that I don’t really know. My work title is information engineer because I am in a company full of engineers. We make software, we build solutions in the fast-paced software world, so my work is a little more specialized. If you want to know the national average on that salary, I’ll let you do your own research, and then I’ll reassure you that I am not making what Glassdoor says.

smart girlI looked on Wikipedia, and the generalist definition of Information Engineering is that we take a software engineering approach to writing and developing information systems, or that mostly we are computer geeks who write. Well…I’m actually a writer who enjoys software systems. I was hired to work specifically on mainframe systems even though I knew almost nothing about mainframes when I joined the company. I think the big distinction is that, as writers, we know how to communicate complex information and that we have knack for learning things. Definitely if I was not into learning, I would stink at this job. But what actually separates me from a “media strategist” in terms of my skillset? That is to say, what if I wanted to leapfrog from my current job into media strategy? Am I working on the tools that might be portable enough to move from one position to another? Yes. And you should too.

In this field, I argue that it is critically important to continue honing not just the technical acumen, but the strategy, to keep abreast of what is going on in other writing areas in order to be as portable as possible. My specific company is using what might not be considered the most cutting-edge authoring tools, so I make sure I learn some techniques and tools outside of my daily grind in order to stay on top of what’s out there elsewhere. So, if you are in a particular niche, say Information Engineering, it is not an altogether terrible thing to make sure that you know that a “media strategist,” for example, is an increasingly complex role that puts you in charge of content delivery in broadcast arenas. Knowing this, in my role as a software documentation writer, I step up on a regular basis and record videos, work with a program called Captivate (an Adobe product) and just play around with what is out there on YouTube in instructional video land. Admittedly, this is never going to put me in the C-Suite of media strategy, but neither is it going to leave me looking like a gasping fish.

Likewise, I try to keep tabs on other media and collaborative tools like #slack or Asana for collaboration tools. If you are knee-deep in managing content projects, you’ll surely want to be adept with these beauties, or at least one of them. My company is currently using Flowdock. It’s not my favorite, but it is a powerful tool, proven with doc-sharing and it gets  around. Some companies are making great use of Yammer as a powerful intranet communication device as well. I recommend at least having a working knowledge of these gadgets. You can’t go wrong, and a broad skills base is never a bad thing, right? Right.

What about the idea of content strategy, you say? These things lean on media management. A recent post was about content, and I daresay I could reiterate that everything I do is about content – content is text, video, graphics, interfacing all of these things into a usable, consumable, findable set or even suite of instructions and understandable items that users can then put to use, find again if necelightbulbssary and move on if not. From an installation guide to a set of scenarios for implementation to third-party software agreements, it all has to be chunked into usable bits of information in the best way(s) possible, and it is up to us – the wordsmiths, the video script writers, the graphic designers, and the UX specialists, to get it right. And often, more and more and more often – we are the same person.

 

 

I suppose all of this goes to say that in the pool of tech writing tools, we aren’t supposed to stay focused only on the items that specifically make us “tech” writers. So grab that pint and start spending part of your day – every single day – finding what’s out there to make you the best writer, editor, designer and consumer. Because that is your new name. It’s been mine for a while. Communications specialist? A rose is a rose is a technical writer is a media strategist is a content implementation designer. All I know is I craft exceptional messaging every day.

 

Nice to meet you.

 

 

Is it Writing or is it Content?

 

 

 

In my not-so-distant past, I read an article by a writer, who posts things in a forum which I respect, pleading that we no longer call our writing Content. She ruminated deeply on this topic, outlining reason after reason why we should respect writing enough to ditch this term, (she called it a “catchall”) and give ourselves the respect that we deserve. She argued that there was, in fact, no way that a writer came up with the term “content” to describe what we put into phrases and paragraphs every day for a living.

I felt maligned. Insulted, even. My feelings were hurt partly because I am currently writing-voicepursuing a certification in Content Strategy. Yes, content. I rather enjoy thinking of my writing as “content.” While I agree that there may be more nuanced terms for some forms of writing – and we may be more specific: poetry, haiku, essay, short story, etc., in the world of technical communication, marketing and corporate communications, what we create is…wait for it…content. But I was more bent out of shape because when asked, I introduce myself as a writer. I rarely qualify this term unless I need to.

I am a writer.writer

The words, phrases, and paragraphs that I construct are inextricably linked to a perception of the company for which I work, its products and its mindset. What I write for them is not the great American novel, nor do I wish it to be. This writer argued that “to write is to find out what you think.” How very noble. I wish that I was finding out what I am thinking while I am creating dozens of web pages that instruct software users in the intricacies of an installation process that is many steps long and requires detailed diagrams to accompany my flowery prose. Alas, I am not. What I am doing is creating useful, tangible prose that goes out into the world and does real good. My writing takes root, grows, and from it blooms a garden of procedures. Those procedures help make sure that your debit card works every Monday morning. It’s a beautiful thing, but I won’t be nominated for a Pen Faulkner any time soon.

Because I create content.

She even maligns content as a marketing strategy, which I found specious. I generate literally dozens of tweets per month in order to forward the ideas and goals of my company. That is writing – and it’s hard writing. I have to be creative, pithy, sometimes funny, sometimes I do a lot of research – and all in a very tight space. It’s called brevity, and Mark Twain said that was the soul of wit. I’m with him. And it’s writing. It’s writing content. That content helps users get to my products and helps people understand my work. Plus it’s darn good writing. So there.

books4People consume my content, not the way they consume a classic novel or even a beach read. They do not recommend my work to their friends as the next great thing to read, and they do not say, “Hey, did you see that great process that Susan just created? Wow! Talk about incredibly lean doc!” That, my friends, is the dream of any software documentation writer, I assure you. But maybe, just maybe, what some of my friends say is, “Susan wrote an insightful blog about the value of Content Writing and how it is important, just like writing your memoir. After all, that technical document will show you how to set up your new laptop so that you can write your memoir. And then you can stick your nose in the air and claim that is real writing, not merely content.”

Refiguring The Primary Measure of Progress

pencilIn Agile Software Development,

“working software is the primary measure of progress” and the manifesto values “working software over comprehensive documentation.”  That is all well and good, but as a writer, I often pause on that one word – comprehensive. I take a moment there and wonder who determines what comprehensive means, and whether sometimes we leave the customer, and the customer’s needs, in the dust when we use that word.

instructions2

Before every developer everywhere has a head explosion, I think we can all agree that expansive documentation is silly and frivolous. So maybe I would swap out comprehensive for expansive. Perhaps I’d have chosen “frivolous documentation,” or “needless documentation.” I’m just not sure I would have chosen the word comprehensive. I get what the manifesto is going for. I do. I want to create lean, usable doc every time. I don’t want to give more than is needed. I want to respond to change fast. My goal is accurate, deliverable doc that addresses stakeholder needs. I suppose I would like to think that, by definition then, my doc is complete, or…comprehensive…in that it includes everything a customer needs. But I agree that I don’t want it to include anything more. I just want to avoid coming up short.

What if I rewrote the twelve principles from a doc-centric focus? Would they work just as well?

  1. My highest priority is to satisfy the customer through early and continuous delivery of valuable documentation.
  2. Welcome changing requirements, even late in documentation. Agile processes harness edits for the customer’s competitive advantage.
  3. Deliver accurate documentation frequently, from a couple of weeks to a couple of months, with a preference for the shorter timescale.
  4. Business people, developers, and writers must work together daily throughout the project.
  5. Write documentation around motivated individuals. Give them the environment and support they need and trust them to get the doc written.
  6. The most efficient and effective method of conveying information to and within a writing team is face-to-face conversation.
  7. Clear, concise documentation is the primary measure of progress.
  8. Agile processes promote sustainable writing. All team members should be able to maintain a constant pace indefinitely.
  9. Continuous attention to linguistic excellence and good design enhances agility.
  10. Simplicity – the art of maximizing the amount of writing not done or words not written – is essential.
  11. The best architectures, sites, and manuals emerge from self-organizing teams.
  12. At regular intervals, the team reflects on how to create more effective doc and then adjusts accordingly.

Okay, so some of this is silly, and I just wasted twelve lines by playing it out all the way to the end, but it was for good reason. Continuous deployment can happen not just with techmanualdeveloping software, but in the embracing of documentation as part of that software, but instead it is often “kicked to the curb” by many teams as a misinterpretation of that one element of the original manifesto.

 

 

It’s not that documentation should be cast aside; it’s that comprehensive documentation is being misunderstood as frivolous or extraneous documentation.

I did not realize that this was a pernicious issue quite so much until I was giving a workshop to a small class of new developers from across my company, hailing from a variety of offices, and they looked at me funny when I described some of how my team does doc (we are pretty good at the whole agile thing, but sometimes we regress into “mini-waterfalls” and I hate them). One of the young devs was astonished that I manage to get my developers to hand over documentation early in the process so that I have it in a draft state, while the code is still being written, not after the code is all in place. It’s a struggle, I’ll admit, but when I this happens, the result is a joyous celebration of shared workload and well-written doc. We can collaborate, change, shift and learn. And the sprint goes more smoothly with only minor changes at the end, not a doc dump in week 4.

To teams who are not doing this: cut it out with the waterfall, guys. Doc is essential, and your users need it. Otherwise, they are calling support and costing your company thousands with every call. Change your practice and build your doc while you build your product.

You might be asking, “How can you possibly write the doc when you haven’t written the code?”

You are not the first person to ask this, trust me. The answer is pretty simple. A long, long time ago, you couldn’t. Or, at least it wasn’t wise to, because it was a redoubling of work. When writers put their stuff into pdfs or word documents, and then had to make major changes, it meant a bunch of editing and rewriting things. Therefore, developers got in the habit of writing all of the code, then examining the processes and hunkering down to crank out the doc. Fair enough. Now, though, we developed wiki spaces and collaborative tech writing tools that now allow inline editing and let developers look at the cool formatting and linking that tech writers have done with our work.

And – before the code even gets written, there is a design plan in place, and usually a design document to go with it. There are code specifications, right? You can have a nice chat with your friendly tech writer and go over this, either through a face-to-face (see Agile point #6) or via any of the vast number of other tools designed to communicate with your team. Before a developer starts coding, there is a project plan – share that plan. Once the general information has stabilized, it’s okay to let the writer have at it. The benefit is that the writer is having her way with the general plan while the developer is coding away. At the end of both work days, the writer and developer have each created something. In a typically short iteration, it is unlikely that the coding will change significantly, so the two can touch base frequently to mark changes (See Agile point #4).

Are there risks to this process? Of course, just like there are with waterfall. Remember that with waterfall, there were a fair amount of times that programming crept right up to the deadline and documentation was hastily delivered and could therefore be sloppy and lacking. And in this method, it is far easier to tell you about writing documentation continuously than it is to actually do it. It takes time, it takes effort, and it takes dedication – because the primary risk for doc is the same as it is for the software: that the customer’s need will change midstream. That problem was (more or less) solved by short iterations in development, and it is (more or less) solved the same way in documentation.mario

The benefit is this – by writing the doc alongside the development, you can be sure that you deliver the doc in sync with the product. You’ll never sent the product out the door with insufficient instruction, and you will never cost your company thousands of dollars in support calls because your customers don’t understand how the product works or how to migrate it. But deliver a product without comprehensive – yes, I’m back to that word – deliver it without a complete doc set, and you may regret it. Trial and error is okay if you want to see how fast Mario can get his Kart down the hill in order to beat Luigi and save the princess, but do you really want to rely on that when the client is a multi-million dollar bank?

I’ve been teaching writing and writing processes for a very long time, and believe me, the action of draft, revise, revise, revise is not new.

It’s just Agile.

 

Why Developers Make Really Bad Tech Writers

 

coding-future

Every now and then, I come across a blog post or other article or column declaring that technical writing for software development is a dying career, lamenting that all of us in the tech writing game should plan our exit strategies and admit that if a product is truly well-designed, our services are simply not needed.

Surely, in some product cases this is true. However, in many high-level software instances, I defy you to successfully install and run the product without some help from your friendly neighborhood tech writer. I pose this challenge because developers think and behave like developers and users think and behave like users. There is a chasm as wide as the English Channel between developer and user, and only the talented technical writer can provide transport safely across.

It’s not that developers are incapable of writing well or that they cannot write documentation, and it is not that users cannot ferret their way through intricate software. Developers could write supporting documentation – IF they weren’t developing that particular product. But alas, developers are too close to the products they are developing. They lack adequate perspective when it comes to their fledgling software, and they have great difficulty seeing it from a user’s point of view. The software, to a developer, makes sense. Developers arrive at a use-stance with some assumptions about functionality and behavior already in hand. So they make lousy content writers because they can’t see it from a user standpoint.

A shift needs to occur in order to artfully create usable content. A developer’s view is, “this is the product, and here are its amazing features,” whereas a technical writer will approach the very same thing from a perch saying, “here is how to do some amazing stuff with this new product.”

Technical writing shifts the focus to a user-centric view that is very difficult for a developer to take. It’s also no small thing that technical writers have been trying to master language, grammar and syntax for the better part of their educations. It’s a sure bet that developers have taken English courses as part of their college education. There are no programmers out there who are illiterate, don’t get me wrong. I work with some really smart people, no doubt about it! But when I tell them that all of our documentation is better perceived in active voice rather than passive, I tend to get a room filled with glassy-eyed folks who really want to get back to their work creating dynamic rules instead of determining whether or not they need a helping verb.

Technical writing in the software field is far from dying. What it IS doing is merging – tightly – with user interaction. It is absolutely, inarguably true that users wish they did not have to read so much in order to get started when they have a new product in their hands. So when we design documentation, we had better design it to work well. Lean documentation is essential – Strunk and White and their mantra “omit needless words” were not kidding.

Working with developers is an art. Letting them do what they do best, and making way for what writers do best, is a science.

I’ve argued more than once that mastering a given tool, like Dita or Framemaker, is fruitful but only if the situation calls for it. I have a totally separate set of tools that I use in my job, and they may or may not prove to be portable, but the skill that is 100% portable is that I can talk to, work with, communicate with, and understand – developers. I let them do their jobs with great enthusiasm, and I encourage them to let me do mine. It’s a synergy that keeps us all smiling, and pushing software out the door at a high rate of success. I work on UX, I design good doc, I focus on usability, I listen to my data.  I look at those sills that simply crackle with career stability. I let the developers tell me everything else that is important. And…I don’t make them write too much. Why? Because they don’t really enjoy it anyway.

And developers make really bad tech writers.

Get Your Umbrella Ready – There’s a Tweetstorm Coming!

twitterstorm1

 In January 2015, a mere 11 months ago, Twitter’s founder, Jack Dorsey, endorsed the multi-tweet “twitterstorm” as a clever means of rapid-fire marketing. He wrote:

tweet

Dorsey also noted that tweetstorming was a pretty brilliant way to maneuver around the 140-character limit, and that it wasn’t the first time that users had built platform features that Twitter designers hadn’t thought of themselves.

In fact, it took Dorsey a series of 17 tweets to talk about his support of Tweetstorming. Charlie Warzel, of Buzzfeed, chimed in quickly with a response that Twitter’s newest trend was totally out of line and “Must Be Stopped.”  Warzel’s reasonable claim? Get a blog.

Dorsey not only lauded the notion of Tweetstorming, but also the introduction of video, photos, and other improvements like direct messaging and a mobile video camera. Many users cheered along with him. Conversing with a group, privately? Hurrah! Capturing and sharing videos right from your Twitter app? Amazing! The Twitter experience can now be full and rich. With just a few taps, you can add new dimensionality to previously flat and non-immersive text-only media.

By July, the concept and term had become popular enough, and had gained enough ground, that Twitter applied to trademark the word, “Tweetstorm.” No lie.

But, wait. What does this have to do with technical writing?tweetstorming

I cannot imagine the things it does NOT have to do with technical writing.

If I am now able to Tweet a set of user steps as a Tweetstorm, steps 1-12, for example in a series as simple as 1/1,1/2, 1/3 and so on so that users can see my Twitter handle and the steps they take, and I can imbed a photo or video along with what they need to do, or even use a screen capture of an on-site step, or a photo of the machine, the shop, the location or the outcome. I have now crossed over in real-time to becoming the most useful tool in the arsenal.

And if I can sit with a developer or support team member and walk-through the issue that a customer is having with the software we have developed, or I can be in the room with my Development Team and a User Experience Designer, a whiteboard and a Product Owner, and live-tweet the whole experience while we develop the documentation, then the medium gets the message.

This particular use of Twitter moves it from social to business and targets my audience with precision heretofore unimagined my Twitter, but that – in eleven short months – could be elegantly applied by businesses like agile software development in a global capacity with full force, especially by teams of document writers who may be located time zones away.

So, Charlie Warzel, while I sympathize that Tweetstorming is indeed not the proper forum for detailing your last evening’s date or repeating the behavior of the passenger next to you on the airplane, I caution that it may be that tech writers will co-opt Twitter in much the same way that thirtysomethings took over Facebook.

Better buy some gtweetstormeraloshes. There could be a heck of a tweetstorm.

Want The Very Best in UX? Hire a Writer

Saying that all technical systems, website creation teams, and indeed software development companies can benefit from a User Experience Designer is like saying that all human bodies can benefit from water. It’s a simple assertion. We all know it, and yet some development groups assume that they know what is best for their customers, or worse yet, they assume their customers know what they want.
What they (the companies, not the customers) do not realize is that the easiest way to enhance the user experience is to hire a good writer. UX design encompasses art, yes, but it must essentially encompass understanding. This seems intuitive, and yet when we look to engage a User Experience professional we do not always assume that he or she is a talented writer.
How do I know this? Well, I used to teach within a professional seminar for the MA in Human-Computer Interaction at a highly-respected university where they were grooming tomorrow’s User Interaction Designers before I took this primo job writing amazing documentation for this crazy-talented company cranking out top-notch software. Surprisingly, though, when I landed here, we did not have a UX guru on our team. I was a bit taken aback that we didn’t have someone like that on the job, but I figured I was new, so I didn’t make waves. Besides, I knew all on my own that really, if there is no art involved, you don’t need interactiondesign, you need interaction writing. So UX talent is not required – a trusted relationship with your writing team is.
I’m not saying that a writer can replace a designer – that’s just bad math. A company that wants to succeed in designing good software, web interface, and more, needs to hire the people who have expertise in software development and web design. After all, writers can’t develop code! But what writers can do is parse the meanings of things. We have the highly developed talent for taking complex ideas of language and inference, metaphor and symbolism, and making meaning from them. And we can tell you when it just doesn’t work. And many of today’s writing programs require classes like Document Design, Communication Design, Visual Communication, and more – things that are akin to how users interact with the ways we are trying to reach them.

storytelling
Writers understand story. We tell stories. And in agile development, what do we call the very things that are on the table for development? Yes! Stories! In scrum meeting after scrum meeting, we task out stories for development, and the scrum master even relies on scenarios to help the team imagine how those jobs will be completed. It is proven in release after release that picturing how a certain element of the product will be used, valued, and consumed by the customer or end-user is a useful tool to the development team. Storytelling allows agile methodology to work, from start to finish. Good writers understand tension and pain, so writing a story or scenario helps to flesh out the documentation that will guide users through installation and troubleshooting. Writers are instrumental in sensing where and when the struggle points will hit for the team long before the software is released for general audiences.
Writers “get” emotion. We deal with it all the time in storytelling. Put a writer in the room in every scrum meeting and just watch how a talented one can help diffuse tense moments over hours invested in an idea that didn’t pan out. It isn’t foolproof, but a writer is also a good catalyst for humor, empathy, kindness and redirection in the heat of the moment. Many writers have a genuine interest in the investment of people, and writers can often help find a silver lining – if there is one to be found – and can redirect the energy. The User Experience is not always found on the outside of the room. Part of the experience is getting the product out the door without trauma.

traumaThe common argument against having a UX person on the team is cost, so often companies toss out the notion as a line-item veto in budget discussions. If there is a place for everyone at the table, that is fantastic, but in the current economy, often we are asked to develop multiple, portable talents. Those who can carry talents across the table are asked to do so. And they should.
The next time you are wondering how your customer might perceive something, I’d ask you to look across the table at your gifted technical writer, your talented copy editor, your incredible documentation specialist, and say, “How does this read to you? What do you think our customers will say? How does this look? What story does it tell?”
You might just be pleased with the answer. You may have found a user…with experience.