User Experience

How We Write: Inclusive Content is Content for ALL

~ Susan Kelley ~ Leave a comment

At a company I worked for a few years ago, I first heard about the concept of “the golden thread.” Essentially, the “golden thread” is a metaphor for the decisions, behaviors, and processes that provide the connection between strategy and actual results. It’s interesting to think that the objective could be something like “to improve the environment” and that there is a thread that could guide you along that path. Or an objective like “to own a home in my city” knowing that, sure enough, if you follow the thread one day you will hold the keys to your own front door.

For a technical writer, the notion of a golden thread should be much more than just a content thread. We employ those all the time. A document that outlines a process, from start to finish, should have a thread running through it. A Standard Operating Procedure manual should have an easily identifiable thread to follow from one process to another, weaving through an entire organization. The metaphor is not difficult to picture.

Although easy to spot in some instances, the notion of a thread tying together so much that it leaves no one out is more elusive. And yet, it is essential in today’s communication.

As a content strategist, I try to be mindful of all of the aspects of inclusivity as I write and design. My audience can vary from newcomers to the product I write for to highly experienced users. I write to the needs of engineers and data scientists, but also new adopters and first-time visitors. But experience level is not the only area where I must think of inclusion. That part is actually the easier lift.

Where inclusivity matters in technical content is in writing in a way that every reader can understand. In best-case scenarios, someone has come before and prepared a thorough style guide that captures clear writing, because writing clearly is more than minimalism. Cutting away formal words when less formal ones will do is one step in the process. I choose to write “let” rather than “enable” – as in “this product lets you plan your wedding” instead of “XYZ software enables you to plan a wedding.” Right?

Erwin Steinberg of Carnegie Mellon University was the first scholar to champion what he called “plain English.” Casting aside passive voice and professional jargon, Steinberg argued that writing simply and plainly was the best approach to complex concepts. His thought prevails today, especially when writing inclusively.

Today, many readers are approaching documentation with some accessibility issue. From low-vision to color blindness to dyslexia, the number of reader-centered accommodations is vast. One would think it would be impossible to consider all of them. And one would be wrong. By choosing to write pages that do not have complex markup that a screen reader wouldn’t understand, you have chosen inclusive writing. By using proper and bold headings, you allow those with low vision or attention deficits to more easily scan and identify chunks of information. Including images only with a corresponding text description assists a wide variety of readers and adds to easy clarity with little effort on the writer’s part.

It’s important, as a content designer, to consistently test and modify documents. There’s no such thing as the perfect, complete document. (Remember, perfect is the enemy of done.) Knowing this, though, it’s equally important to revisit your writing and your language choices as regularly as possible to see where you can improve. Scheduling regular reviews of your own work is the best way to see where you missed and where you didn’t.

When creating content of any kind, keep a few numbers in mind:

  • 26% of the US population has a disability
  • 20% has a mental illness
  • 5% is LGBTQ+

So what does this mean for writing? Glad you asked.

  • Monitor cultural references that not everyone will understand
  • Use preferred pronouns when writing personally, neutral pronouns whenever possible
  • Don’t assume that readers are heterosexual, male, female, young, etc.
  • Use gender-neutral professions and titles (e.g. firefighter, not fireman)
  • Never assign a gender to a quality (that is, strong is not manly and feminine is just off-limits)
  • Add detailed descriptions for links, not just “click here”
  • Never use ableist language (lame, blind, dumb)
  • Don’t swap out mental health assignations for daily emotions (someone who is meticulous is not OCD)

Along with these practices, keep in mind that shorter is better, jargon is awful, and if you have to use some fancy words you should build a glossary. Never rely on a stereotype and don’t assume a joke is funny to everyone. Absolutely choose welcoming topics, consider readers’ needs, and look for ways to improve every day.

When all is said and done, if you aren’t sure – ask. Rarely do people who are asked for their input respond poorly. People who are not considered or included – now they can get a bit (justifiably) upset.

Write on.

Advertisement

Let Me Ask My Analyst.

~ Susan Kelley ~ Leave a comment

Such a phrase from the seventies, right? Am I dating myself? Maybe, but hey, I was just a kid back then. I’m all grown-up now, and gaining insights by the day.

The goal of insights are, just as they were in the seventies, when everyone was seeing the original “analysts,” better decision-making. Not much has changed.

I take that back.

A whole lot has changed. We couldn’t have imagined, (or could we?) back when computations were done by punch-cards, that we’d no longer be shrink-wrapping user manuals, but instead looking to true trends analysis to see what our users want from our writing. Now, we are in the realm of truly seeking what patterns in our content are useful and what can go by the wayside, because we know, for instance, that our users no longer need to be told to enter their credentials upon login. They get it. They are familiar with creating passwords, and the concepts that were once totally unfamiliar are now second nature.

It’s a whole new frontier.

Now we are in a new domain.

Companies ask us not to be writers, actually, but content creators, content strategists. I used to scoff at that title, because anyone could use it. There is no credentialing: a licensed content strategist is a unicorn. And yet, real industries call for those who can produce (and produce well) two types of content: structured and unstructured. Yikes!

Structured content can be found. It has a home, a place, it is text-based in the case of email and office or web-based documentation. Unstructured content may include an archive of videos, or even non-text-based things like images and diagrams. There is a huge volume of this type of content, and yet it falls still under the purview of we, the content creators.

Those of us who used to be called “technical writers” or even “document specialists” or something like that find ourselves of course wrangling much more than documentation, doing much more than writing. So the issue became: how do we know if what we are doing works? Are we impacting our audience?

That’s where analysis comes into play and matters. Really, really matters.

Why spend hour upon hour creating a snazzy video or interactive tutorial if no one will watch or, dare I say, interact?

That’s where content analytics comes in.

Analytics measures. Photo credit: Stephen Dawson.

The whole goal of analytics is for us to know who is reading, watching, learning – and then we can improve upon what we’re building based on those engagements. It does little good to create a video training series, only to discover that users don’t have an internet connection on site to watch YouTube. Similarly, it’s not helpful to write detailed documentation and diagrams for users who prefer to watch 2-3 minute video step-throughs. It’s all about knowing one thing: audience. The essential element, always.

The central theme in Agile development, after all, was learning to understand the customer, so the essential element in designing better content, sensibly, ought to be the same thing. When we hunker down and learn what the customer really wants, we develop not just better software, but better content of all types.

With metrics on our side, our companies can identify just what content has real value, what has less, and what can really be dropped altogether. Historically, academic analysis was held to notions of things like how many times a subject blinked while reading an article. (Ho-hum.) Now, though, we can measure things like click-thhroughs, downloads, pauses during video, hover-helps, and more. How very, very cool.

Multiple screens to choose from. Photo credit: Alexandru Acea on Unsplash.

Historically, content analysis was slow, time-consuming, and it was a frustrating process with limited accuracy. Now, though, we can measure the usefulness of our content almost as fast as we can produce it. Content analytics are now available in a dizzying array of fields, reflecting a vast pool of data. The level of detail is phenomenal. For example, I’ll get feedback on this post within hours, if I want. I’ll create tags and labels to give me data that lets me know if I’ve reached the audience I want, whether I should pay for marketing, whether I might consider posting on social media channels, submitting to professional organizations, editing a bit, and so on. I may do all of those things or none of them. (Full disclosure: usually none, unless one of my kind colleagues points out a grievous error. I write for my own satisfaction and to sharpen my professional chops. Just sayin’)

Believe you me, the domain of conent analysis, in all areas, will grow and grow. Striking the perfect chord between efficiency and quality is not just on the horizon, it is in the room. AI-powered writing and editing, paired with the streamline of knowing we’ve reached the proper balance of placement and need – it’s not hyperbole to say the future is here. It’s just turning to my ‘analyst’ to ask whether I’ve written my content well enough and delivered it properly.

My product teams, my business unit, and my company are all grateful. And my work shows it.

Writing From the Other Side of the Screen

~ Susan Kelley ~ Leave a comment

What it Means to be a UX-centric Tech Writer

Image: UX Planet

I have been part of the information design and delivery field for nearly two decades now. In one form or another, I have been handling technical information, whether in software, government, or higher education for the better part of my career. It sure has changed quite a bit since I first mapped out my first website, I can attest to that.

To begin with, technical writers came along as the necessary bridge between subject matter experts and customers or consumers. In my original field of higher education (I taught at an R-1 University for quite a while), we worked on the notion that some people were suited for engineering, development, science, and so forth, and some people were suited to understand and explain it in laymen’s terms. For quite some time, passive voice and distanced-language was the norm.

A paradigm shift occurred when we all realized that technical manuals – installation guides, user documentation, and troubleshooting – were all far more palpable if we just wrote them the same way we would explain the processes themselves. Eureka! “Plain Language” was born. One of the leaders in the charge was teacher and scholar Erwin Steinberg. Steinberg championed many advances in technical and professional writing, and moved the needle considerably in conciseness and clarity. (And yes, indeed, Carnegie Mellon is both where I studied and where I taught, so to say I am an acolyte is an understatement.) Steinberg’s text, written along with William Schutte, “Communication in Business and Industry” is arguably almost as relevant today as it was when it was published more than fifty years ago.

What has changed in the years since that first technical writing undergraduate major was launched is the centricity of the way we write technical text. When technical writing fully hit its stride, not long after the personal computer and internet became a true staple of both home and work, the locus of technical writing shifted from the technical user to the everyday user.

Specializations emerged that are now necessary to our function in everyday business that were unforeseeable before. UX and Instructional designers now must envision and create personas for the users in their fields, and imagine who is on the other side, who is consuming their creations and not just how, but why.

Just as automobile designers, fashion designers, and creators of every type in every field, now those of us at keyboards in the technical realm turned to think of our end users not as savvy experts, but as new consumers with specific desires and needs that must be filled, or who would move on to companies with products that could give them what they want at breakneck speed.

In the early 1990s, a hastily written user guide could balloon into the hundreds of pages if we weren’t careful, and little thought was given to the overall design.

Now that we tend to write by working in an Agile environment, more on board with the development team from the start, and with more input in the scope, we can bring a design thinking mentality to the process. The difference between writing and end-to-end manual and wireframing a useful knowledge base website is vast – and fun!

Thinking like a strict technical writer, we might cover every detail, from turning on the machine to creating and logging in with user credentials, to an entire step-by-step process that users are now wholly familiar with.

Thinking like a UX writer, though, we can liberate ourselves from much of that clutter by recognizing that our clientele know full well how to turn on their machines, they understand what it means to log in, they don’t need words like “navigate,” “click” or “enter.” Those are all useless fluff the same way that passive voice once was. The sooner we move on, the better.

As a strict tech writer, I found that rarely did my colleagues engage in discussions with customers about how to improve or streamline their documentation. I got feedback from peers that were mortified at the thought of interacting with their users. But in a UX writing environment, it’s informative and enjoyable to gather feedback from how our users actually apply our work. Knowing what works, and what doesn’t, what is exciting and what fails, helps to create better and better documentation.

In the new formats we are applying, UX writers often have limited information bandwidth, since many of us work on apps and app messaging. A UX writer could realistically have to craft a message that uses:

  • A 30 Character Headline
  • A 45 Character Body
  • 25 Character Buttons or Tags

With these limitations, UX technical writers must be concise, thoughtful, and creative to get the job done and done well. We have to consider user-types, roles, and information delivery in microcopy without losing messaging.

This is, in part, why companies like SalesForce have turned to humor in their technical copy. There’s little room for elaborate text, so having a bit of fun with graphics or pop-ups along the way eases the tension. Take, for example, the cute little bear they use on their learning platform. Not exactly a serious guy.

If you’re interested in upskilling a bit when it comes to Microcopy, a skill that is fairly essential in a technical UX sense, Udemy has an excellent short course. Surely other providers will follow, but so far this is my preferred resource. (Note: I get no reward, it’s just that I have found Udemy to provide good content in this area thus far. Please leave a comment if you have found other useful tools.)

Any of us who fancy ourselves “Content Strategists,” “Content Designers,” or just user advocates when it comes to text and information delivery will be coming up short if we fail to consider UX a vital part of what we do.

Long gone are the days when we must write a soup-to-nuts technical manual. Gone are the users who do not understand how to log in, how to set up credentials, how to read a page, navigate through menus, and so on. Solid research tells us that toddlers are capable users of iPads and cell phone screens. Today’s teens have no notion of what a rotary dial phone is or could be used for, and little idea of the purpose of a cassette tape, but are fully versed in the multitude of Snapchat filters and can adapt to a new iOS software update with no information in under 24 hours.

That, my friends, is our audience. A thousand-page manual is useless, but a thoughtful troubleshooting guide is golden.

Think about who is on the other side of the screen, what troubles they may encounter, and solve them. IF the interface is well-done, the documentation can (and should) be minimal. The help should be robust, and the instructions few. Provide a backup plan for pain points, and explanations for tricky areas, remembering that the tricky areas spotlight poor design. If we write as UX advocates, we will never be out of work, because our designers will help us design better, and there will always be more users for our greater creativity.

Getting SMART in 2022

~ Susan Kelley ~ 1 Comment
Photo by Marcus Winkler on Unsplash

It’s that time of year. A fresh, new start. New Year’s resolutions have been made (and some have already been broken), a crisp new calendar is on our desks, waiting for jotted notes and creative meetings.

It’s the time of year for setting goals. Businesses set their goals for the year, what their bottom line should look like, how to inch out ahead (or sprint, perhaps) of their competition. Things feel new, even as it is the dead of winter here in the US, where I sit to write this.

Many of us are asked to think, and think deeply, about what we hope to do with the next twelve months, even as we reminisce about the months we’ve just left behind.

2021 was not an easy year for many of us, finding our way through many changes – in our work environments, our work styles, our social gatherings and tolerances – much is indeed different. But rather than waxing too poetic, it’s time to get down to brass tacks.

We as technical writers have to set goals for ourselves that outpace those of our developers, our scientists, our teams. There’s more to us than just batting cleanup for the tech teams. We know that. So how do we set goals when so much of what we do depends, wholly, on the work of others?

We do it by relying on the business-tested model of SMART goal setting. Many of us are familiar, but for those who are not, I will briefly elaborate.

SMART goals are thus:

Specific, Measurable, Achievable, Relevant, and Time-Bound.

I daresay that the two most important words in that acronym, at least as far as I am concerned, are Achievable and Time-Bound. As a writer, I know how to be specific, and relevancy is the home base of technical writers. I truly want to focus in on Achievable first.

I talk, from time to time, about law school. Indeed, even at my age (not terrifically young), I’d like to go to law school. I cannot, though, set “Get a law degree” as a SMART goal for 2022. It simply takes too long, and it isn’t achievable. It is something I can achieve in a few years, if I ever get started, sure, but not before I turn the calendar to 2023. So instead, if I want to be serious about it, my goal should be: “Study for and enroll in the LSAT by July, 2022.” That is a specific, measurable, achievable, relevant, and time-bound goal.

How so?

I stated very clearly what it is – study and enroll. (Okay, I suppose that is two goals rolled into one, but they do go hand-in-hand.) I know how to measure it – my enrollment will be provable with a receipt that I’ve paid for and scheduled the test. It is achievable – there’s no reason I can’t prepare in 6 months, realistically. It is relevant – I need the LSAT in order to reach my larger goal, and it is relevant to my career in that it is continued learning. And it certainly is time-bound, given that my deadline is July.

I probably will not take the LSAT this summer. Or maybe I will. We’ll see.

As a professional technical writer, I can hone in more specifically.

My company is adopting a new technology to assist users by adding in-line help to our customer-facing text. It offers targeted help messages, and on-demand walk-throughs. Not everyone on the technical writing is a superuser of this software, but I think becoming one of the experts would be a great thing for me. So… I’d write a SMART goal something like this:

Support technical content team adoption and understanding of customer experience software by attending two webinars and presenting learning to the team by Q3.

Here’s another:

Implement a team adoption and use plan for new customer experience software by becoming a lead learner/power user of the tool and updating the technical content strategy team monthly in Q3 and Q4 at lunch and learn or content drop-in meetings.

Both of these demonstrate ways that a technical writer can work outside the general product domain, but still provide measurable value, and therefore important goals, as a writer.

What if your primary direction, though, is actually product improvement? Well, then, SMART goals are even smoother to set. Think about the specific thing about your product or service that you think needs more clarity. (Let’s say, a migration guide.) Then determine the part(s) that you can improve most effectively right away. (This part is achievable.) Recognize how you will break it into component parts. (How will you measure your progress?) List why it is meaningful to your team. (Relevancy is all over this part.) And last, set a finish date or intended submission. (This is how you make it time-bound.) Here’s an example for that:

My goal is to revise Sections 1-3 of the User Migration Guide to minimize sentence length and remove broken URLs to improve user experience and decrease page load time. By the end of Q2, I should have the first revision ready for review by SMEs and by the end of Q3, a final version ready to release.

This kind of straightforward documentation thinking is how verbose, “clunky” documentation is streamlined and improved every day. Just bringing it up in a meeting with your manager or team can help to spur conversations about ongoing ways to improve documentation that might otherwise be considered final, and not touched again until the next release boundary. With today’s tools and more consistent documentation updates, users really appreciate the tweaks that we can make, like omitting needless words, and broken link cleanup!

When you think about what you want to do in 2022, don’t limit yourself to a specific area of work. Think about whether you want to learn a new skill (Programming in Python), or add another area of product knowledge to your growing arsenal (check out the latest in APIs or integrations), and see where that leads you. And absolutely remember to toss in a personal goal or two (or three). As for me – Law School is not out of the question, but becoming a yoga instructor is definitely on the goals list.

And to that – Namaste.

Next Gen Writing: Sealed With a KISS

~ Susan Kelley ~ Leave a comment

I often hammer away at this thought, but coming to the close of 2021 and heading into another year of technical writing, closing out the first year of a new decade, it seems like it’s time to revisit.

The KISS approach has worked in many other areas of life – Keep It Simple, Stupid.

It’s a bit like the slogan Bill Clinton used to keep in mind: It’s Always the Economy, Stupid. Not that any of us are stupid – quite the opposite, in fact. Many of us are so smart that we naturally assume that those reading our documentation are equally bright. While that may be the case, often our consumers are bright and talented in other areas. Alas.

In technical writing, a few factors drive change and demand a better strategy. We, as writers, call for more user-friendly tools in our writing. Along came Confluence and SharePoint, along came markup, we got to use DITA.

Our managers expected measurably consistent outcomes and cost control in the content we produced. End-users required more user-friendly content. The evolution continues.

Each of these demands is the consequence of expecting easy-to-use methods and tools. Technical writing, the product, is a tool for everyone. What used to be in the rare air is now at everyone’s fingertips in a highly mechanized world. We used to refer to a revolutionary “plain language” style of writing, and now it is merely dubbed “Simplified Technical English,” the demand for which keeps growing.

There is even a dictionary of Simplified Technical English, and it comes with its own acronym, STE, so it looks as if the trend is here to stay. This way of writing improves clarity and quality, but along with those improvements come some difficulties. Any time there is a standard, there are rules. Can we commit those rules to memory as we have grammar and our beloved Strunk & White? Likely, no.

Instead of rote memorization, we look to tools that incorporate STE for us – again, back to those easy-to -use methods to help us out. We want to lessen the cognitive burden, freeing up more so that we can understand the technologies about which we write. Microsoft helps every time it incorporates a spell- or grammar-check into Word, and Grammarly or Acrolinx are to our benefit, to be sure. All of us in the writing game have a love/hate relationship with authoring tools designed by developers, but until we hybridize our own talents, here we remain.

It is key to remember that a great deal of our output is targeted at an international reader. Adopting STE, or Plain Language, is truly beneficial when we localize content. While we should stay far, far away from idiom, trending toward casual writing is in our favor. Using STE as a guide, and truly standardizing our technical writing across all documentation in a given organization is the single best way to ensure that our technical content is to-notch all the way around.

It may seem as though I am beating the proverbial dead horse in this writing, except that end-of-year is precisely when companies are looking to evaluate the cost, quantity, and quality of content produced. Measuring will help improve overall performance and delivery, and will help create harmony among writers and consistency between texts. Why does that matter overall? Because the team that can write with one voice, and that voice is Plain Language, STE, will project to the end user that the company, and its products, are synchronized in performance and quality. And that, my friends, is the penultimate achievement of any writing team.

Best of luck at year-end, and on into 2022 we go.

Are You a User Advocate? You Should Be.

~ Susan Kelley ~ Leave a comment

Technical writers wear a lot of hats. That almost goes without saying. And yet, I said it. We are called upon to have “jack of all trades” qualities that stretch into the domains of information design, quality assurance and testing, marketing, and more. There are splashes of business analysis (oftentimes more than splashes), and creativity, lightweight programming, and definitely time management planning.

It takes a natural curiosity and desire to learn to be a successful tech writer, and anyone without significant attention to the details that matter won’t get far. Getting bogged down in minutiae and useless side-work won’t do you any good, but the meat and potatoes – the grammar and syntax, the user understanding – that is where the rubber meets the road.

This is why I call out the question. Are you a user advocate? If you don’t approach all your technical writing as a pathway to advocate for your reader, you are likely missing a great opportunity.

Start with Help Content. Everything from software applications to mobile phone instructions beg for a rich help content guide for users. Without a doubt, users come to the Help when they have a pain point. They are either brand-new, looking to get up and running, or they have hit a snag, and they want to get back at it. There’s no time to waste, so getting the Help right is crucial.

The only way to draft an exceptional Help Content section is to think like your reader, and advocate for her. “What would annoy me most? How can I fix that? What would make me happy? What is the simplest path forward?” When you answer these questions, you write good (even great) Help.

Process Modeling is another area where advocating for your users is what puts you over the top. Remember that there are users out there who thrive on the IKEA diagram style of directions for process, just a simple picture show-and-tell, but there are also those of us who totally cannot follow those drawings and are utterly lost from page one. To advocate for both sets of learning styles, a good tech writer will layer-in a smattering of both, covering the bases visually and linguistically with a seamless pairing.

If conveying information to users in a way that meets their needs means adding flow charts or tables, then model that process from end-to-end and put yourself in your user’s shoes. It works every time.

Rinse and Reuse is a motto I’ve lived by as a user advocate. Many writers and managers call this “single sourcing” but that is just a fancier way to say, “if you wrote it well the first time, don’t write it again.” Walk yourself through the user’s journey, and if there is another place to use your elegantly written prose, do that. Familiarity doesn’t breed contempt, it breeds comfort. A user feels heard and recognized when he sees the same comforting words again. He feels knowledgeable. Wise. Learned. So, rinse off your documentation, excerpt it, use it again. Either link back to the original or include a whole page. It’s comfy.

Design like a trainer. User advocacy in technical writing means, in large part, thinking like a teacher. We never want a reader to feel like we are being condescending of course, but we do want to be on the journey with him, teaching him as we go. Incorporating good text design, like a lesson plan, is absolute user advocacy. Good teachers seek to elevate their students to a new level of accomplishment, and good tech writers should seek the same outcome for their readers. Have you noticed how much friendlier installation and process documentation has become? There’s a reason for that. Just as teachers no longer scold kids with a ruler to the hand, tech writers have softened their approach as well. It’s about elevating the experience, not just imparting the information.

Do these fit well and match my outfit?

By and large, if you put yourself in your reader’s shoes and ask yourself, “Do these fit well and match my outfit?” then you have begun the advocacy path to technical writing. More simply put, write like your reader, and speak up for her. You’ll improve your product, your outcome, and you will, at the end of the day, be a much-improved technical writer.

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

~ Susan Kelley ~ Leave a comment

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

~ Susan Kelley ~ Leave a comment

 

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?

~ Susan Kelley ~ Leave a comment

 

 

 

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

~ Susan Kelley ~ Leave a comment

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.