Work-Life Balancing That Works

~ Susan Kelley ~ Leave a comment

Image courtesy of Yuki Nakamura on Unsplash.

This week is the Cherry Blossom Festival in Washington, DC. It’s less than an hour by train from my house, and is arguably the prettiest harbinger of spring in the mid-Atlantic corridor. Saturdays and Sundays in the limited-run showing of the more than 3,000 cherry blossom trees are a chaotic influx of visitors from around the globe. Busy is a deep understatement. Crowded doesn’t begin to describe.

A fair-weather weekday, though? That provides nearly perfect viewing conditions for the gorgeous 1912 gift from Tokyo.

Alas. That would interrupt a work day. If I took the 2pm train to DC and wandered about the tidal basin for a couple of hours, the earliest I could be back home would be, say, seven p.m. assuming I stop for a bite to eat and don’t rush to ride the train home at 5pm with all of the commuters.

And yet – I’ll likely do it. I’ll feel no guilt about stepping away from my desk at 2, because it’s very likely I’ll sign back on at 7 or 7:30, and will have started my work day at 6:30 a.m. as usual anyway. I’ve been known to crank out some pretty great work at 10 p.m., or to manage some very focus-heavy work before 7 a.m. EST. I very frequently get some good writing done on Sunday morning, or a rainy Saturday afternoon.

Sometimes the 9-to-5 model of work doesn’t work.

Even before the pandemic, strict adherence to a 9-to-5 schedule was on its way out of favor. The onset of COVID-19 made it nearly obsolete not because workers were taking more time for themselves, but because working from home allowed them to take less. Throughout the pandemic, I’ve been working for companies whose workforces span international time zones, sitting on multiple continents. Working a traditional office schedule just no longer seemed pertinent.

There are days when I wake up at 5 a.m. and am energized enough to get started. There are other days when I prioritize going to the gym in the morning, meaning I won’t be at my desk until 8:30 or so. I am a fairly morning-centric person and I like the time to work without disruption from team members with questions or tasks. Working a bit on the weekend allows me the same kind of freedom from slack messages and time sensitive emails. Focus is good for this writer.

I’m not here to brag about my weekend work ethic, I assure you.

I’m here to point out that if you are super-efficient at 8 p.m. after you’ve put the kids to bed and are beginning to settle your mind into tasks you can handle, then by all means work at 8 p.m. But if you choose to do that, don’t feel tethered to your desk from 9 a.m. the whole way through, because that is where burnout happens. Burnout doesn’t come from logging time on a Saturday or before the rooster crows. It happens from feeling the need to be present at your desk even at your lowest capacity. If there are times of day that you are not productive, it’s likely those are the times you should go for a walk, make a grocery run, meditate, read a chapter from that book on your nightstand. You get what I’m saying.

Shed the idea that opening your laptop at 10 p.m. is a sign of overwork. If you provide room for “me time” when it is best for you, then you can also provide “work time” when you are at your peak.

I get it, sometimes you simply must be present for the typical work day to answer emails, attend meetings, and all of those necessary elements of our jobs. But there are other times when you can totally work “outside the box,” and not only should you, but you should also then take advantage of offsetting your time.

Take some time to smell the roses.

Or the cherry blossoms.

Advertisement

Minimum Viable Documentation: the Bare Minimum Doesn’t Have to be Bare.

~ Susan Kelley ~ Leave a comment

Do less with more.

Practice minimalism.

Do “documentation triage.”

All of these are concepts we’ve heard about, and have been tasked with understanding and implementing across our documentation practices. But what are they and why do they matter? And how will creating “Minimum Viable Documentation” impact what we do and how we do it?

We learned ages ago in the software development world that “perfect is the enemy of done.” That applies to writing as well. We can move participles and conjunctions around all day and still never achieve perfection. As a professor, I told every single one of my students, usually on day one, that they would never receive a 100% on any paper they submitted to me. I wholeheartedly believe that there is always room to improve. I think the best writers throughout the history of time would agree with me. As a teaching tool, I often used e. b. white’s “Once More to the Lake” as an example of how revisiting a piece of writing many years later can fundamentally shift it to the better without trying to change it in tone or style whatsoever.

So how do we create documentation that is good enough without sacrificing our standards?

The first step, according to esteemed technical writer Neal Kaplan is to “prioritize ruthlessly.” It’s vital to look at what actually needs to be documented, and focus on that. The rest is, as they say, gravy.

When we are early in our writing careers, and sometimes just when we are early in our writing projects, we think it is important to document everything. No step or function should be relegated to the trash heap. We fail to plan, and therefore plan to fail. When we look at documentation as a broad-sweeping need for users, we miss the point. We lament that no one reads the documentation, but we keep writing it. Why? Are we hoping users will do an about-face? They won’t. Ao as my high school English teacher reminded us time and again: plan your work and work your plan.

That planning is what Kaplan calls triage. I just call it good practice.

  1. Start planning long before you start writing.

2. Give every task an estimated level of effort – even if it’s a guess, start guessing.

3. Use documentation architecture – design your plan, and plan to grow.

4. Stand by your plan,but be open to changing it.

See how not all of those numbered items are aligned? I chose that architecture because the first one is vital, the others then follow. Plan. Plan. Plan. They are each important, though. Following these 4 will result in documentation that gets the job done, doesn’t leave bare spots, but isn’t full of extra bells and whistles.

You’d never hire a contractor to work on your house without an estimated level of effort. You want to know how long that project will take, how difficult it will be. Your contractor lets you know it will be a couple of days, or a couple of weeks. It is an estimate and it is not a firm commitment, but it sort of time-boxes the work to be done. It’s rarely spot-on. You might have an architect that shows you how fantastic a skylight would be, but once your contractor starts the work, he tells you that will be a challenge to complete based on the roof, the seal, whatever. So you nix the skylight.

Your contractor takes a dive into the work and then recognizes that perhaps you would prefer the sink on the other side of the room, or maybe you want a different fixture than the one you saw in the store. You can put your foot down based on time, cost, and aesthetics. It may be that the extra time required to purchase a new fixture will change the look of the room enough that the pivot was worth it.

On the other hand, maybe the new fixture is out of budget or will take too long to install. It’s something you can see having installed in a year or two, but it isn’t necessary right now. Okay, so you know that down the road you have some more work to do, but getting the standard fixture installed keeps you on time, on budget, and your rom is usable.

Usable.

That is the key word in all of this. Usable.

Our “bare minimum” is hardly bare when our documentation is usable. Minimum viable documentation is choosing to follow the design plan your architect and contractor gave you, but adding all of the decorative touches later. You’ll have a fully functioning and attractive room with the key elements. You can add the flourish later, if you add it at all.

I’ve extended this metaphor about as far as I want to, and if I continue to write I will violate the basic principles of conciseness. Tell your teams that Minimum Viable Documentation is not the writing equivalent of a rough draft. It is the equivalent of writing a 2-page paper when you recognize that a dissertation is unnecessary. You can be sure that every comma, bullet, and number is correct if you write briefly. The viable minimum is so much better than the bare minimum, and worlds better than the alternative.

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.

AI Isn’t Out for Your Job

~ Susan Kelley ~ Leave a comment

Because We Can’t Even Agree On What It Is

Photo courtesy of Possessed Photogrpahy.

There is such a swirl of discussion around Artificial Intelligence and whether it will supplant human work. This largely stems from a real misunderstanding of what AI is and what it can do. According to IBM, Artificial Intelligence is: “the science and engineering of making intelligent machines, especially intelligent computer programs. It is related to the similar task of using computers to understand human intelligence, but AI does not have to confine itself to methods that are biologically observable.”

There’s a lot packed into that definition. No wonder people don’t know quite what to make of it!

It seems to me that the biggest challenge is that people mistake Intelligence for Sentience. While humans certainly possess both, it’s not even a realistic goal in some ways to presume that we can master Artificial Sentience.

What do I mean by this?

In a nutshell, “sentience is the ability to feel, sense or experience perceptions subjectively. Those working in the field believe that capability to be decades away, if achievable at all. Building self-awareness into a machine is an unlikely undertaking, anyway. To reach that state, researchers would have to build programs that achieve generalized intelligence, a single learning machine with the ability to problem solve, recognize environments and changing requirements, and the capacity to learn more. Once that capacity is established, the next step is just reaching the edges of the potential ability to learn consciousness.

Therein lies the rub. A machine is unlikely to “learn” how to “feel,” since the uniquely human capability of complex emotions is perhaps the ultimately most difficult thing to teach. Just as a machine has no conception of physical pain or healing, the ability to feel attachment or loss is not necessarily a programmable skill.

No one in the field claims that a Roomba has any particular attachment to the floors it vacuums, despite the fact that it does indeed learn what the obstacles to successful vacuuming are. No one believes that a robot vacuum enjoys the sensation of a 120-volt charge running through its wires, even if we imagine those wires to function much like veins.

Robots still can’t feel.

Robots can mimic, absolutely. They are fantastic at aping what humans do, if they are taught to do so. Within series after series of If/Then statements, a computer can perform all sorts of functions. My robot vacuum “understands” that If there is a chair leg in the way, it should rotate 30 degrees and try again. If the block is still there, it will rotate again an again until it is able to move past the obstacle. With the most recent robot vacuums (to stick with this example), the vacuum “knows” that the chair is there and “learns” to avoid it, unless it arrives at that obstacle and finds it has been moved. That said, the vacuum is not frustrated by the obstacle, nor is it relieved when the chair is moved to another room.

I think of it often as similar to what I learned in my first college linguistics course: animals can communicate, but they do not have language. That is, my dog can let me know when he is happy, but he cannot tell me that his father was poor but honest. Machines can learn, but the challenge is that they cannot emote. They can mirror emotion, sure, but to have original and unique feelings about their situations? No. At least not yet, and not for the conceivable immediate future.

But that does not mean that machines cannot learn. They very much can. Just as a third grader can sit quietly, ingesting information and retaining it for future reference, a machine can do the same. A student learning multiplication tables soon learns that 5 x anything can only result in a number ending in 5 or 0. A machine has the capacity to learn and retain that information and apply it to millions of situations, millions of times faster than the human mind can do. A machine can aggregate vocabularies, numerical sets, geographic data, and more – all at a rate far more effectively and efficiently than the human brain.

That’s why machine learning and artificial intelligence are thrilling and fantastic.

But until that computer program can harness things like anticipation (that the car in the next lane is looking like it will merge into yours), or fear (that the spider crawling up the side has the potential to cause damage), and responds accordingly, our jobs are all safe. Machines can certainly learn to edge over if a car is too close or to restart if an interloper is nearby, but it does not have the capacity for self-awareness.

We mustn’t confuse intelligence with sentience, and if we do that, we’ll soon welcome the advancements of AI and machine learning, harnessing them for what they are.

But remember, too, that until the machine can understand notions like initiative, relaxation, and joy, it remains a tool for us to use. And remember, too, that it may well be the mindless robots may be our biggest threat, not the ones that could one day feel and thus bring us things like helpfulness, empathy, and emotional support.

Susan is a technical content strategist and researcher of all things automated. She lives in Baltimore with her two dogs and snuggles with them when she’s not on her bike or swimming laps in the pool. She is an avid traveler and reader of nonfiction. Subscribe to this blog to learn more about technical writing, communicating, and machine learning within those domains.

How Technical is a Technical Writer? (Answer: It Doesn’t Matter.)

~ Susan Kelley ~ Leave a comment
Photo courtesy of Matt Artz on Unsplash

Indeed.com offers a handy definition and guidebook to becoming a technical writer. They define techincal writer as follows: “Technical writers develop documents, user guides and other written materials for technical products and services.”

Not sure I agree. But my disagreement comes from what they write after the definition:

  1. Earn your bachelor’s degree.
  2. Pursue a technical writer certification.
  3. Create a portfolio of samples.
  4. Build up your professional network.
  5. Develop your industry knowledge.

Umm…okay, but also wow. I am on board with #1 because hey, no matter what undergrad degree you obtain, chances are you will take at least a couple of English classes, and at least one of those will be composition-focused. So that’s fair. Next, though – pursue a technical writer certification? Let’s see here…I’ve been working in the field at progressively more senior levels for more than a decade and I do not possess such a thing. Is it perhaps advisable? Okay, yes, but…and this is a significant “but,” it is non-essential. (To be fair the reason I do not have such a cert is that I never worked for a company that would pay for it.) As for #3, a portfolio of samples? One would hope that a good interviewer will be able to ferret out whether you are a capable writer by looking at some college-level essays or asking you to write to a specific prompt. And then? Build up your professional network. Let me tell you, kids, I did this by being a professional. I did not have a network per se until I actually joined the profession of technical writers. As soon as I did that? Blammo – of course I had tons of peers and mentors to choose from. More importantly, I had not only guides in the field of writing but…you guessed it…in technology.

Which brings me to – how technical do you need to be?

I interviewed for my first role as a technical writer having zero real world tech experience. That is to say, I was hoping to work for a company that handled mainframe development. Developing for developers. I knew nothing about mainframe, including how exactly it worked. I ‘fessed up to this in my interview, but also emphasized that I am exceptionally good at self-organizing, I am not afraid to ask questions even if they may make me look foolish (they rarely did), and that I am eager to learn new skills and concepts all the time.

I got the job.

I worked in mainframe software development for quite a few years before moving on. I wouldn’t even have moved on from that company, but I was physically moving my location to a new city, and the position was not remote.

I was not technical.

I later took a position as a proposal writer in the federal government space and knew very little about the automation my company was building, but I had serious chops as a persuasive writer, so again – that is what got me the job. I am a writer, not a developer. I need to learn and understand the technology, not master it.

Now, take all of that in and understand this part – if you can amass technical skill even as a tech writer, you are worth more, and I don’t just mean in dollars. You are a valued asset because you can do things like suggest tweaks to the design, find issues with code functionality, and view the process from a product perspective, not just as end-user. If you have technical capability, you understand what goes in to the product – how the sausage is made, to put it in some vernacular.

Let’s go with that metaphor, in fact – how the sausage is made.

Imagine that you are tasked with writing technical copy, or user manuals, for someone using a new kind of Italian sausage. It’s the kind with the casing and it comes in links, and you need to write about how this can be used “in the field.” There are not installation instructions, but still you are not writing recipes. You are writing the user manual. It’s stuff like “do not remove sausage from its casing,” “cook to an internal temperature of 160,” “refrigerate after opening.” Straighforward, right? Except if you are the original writer of all of this, is it not important to understand that the casing is what holds it all together, the temperature is the safe point at which humans can consume without detrimental effects, and that refrigeration ensures longevity of the product? Of course those are good things to know. You can’t just make that stuff up, arbitrarily deciding on a temperature and whatnot.

You need to have some technical knowledge. But you do not need to know: how the pork is rendered, what farm it comes from, how the machinery operates, what credentials the personnel have who staff the factory, and so on.

In the sausage instance, you would need to be comfortable researching (or asking) abotu safe temperatures and shelf life, but you would not need to be comfortable slaughtering a pig.

Get it?

The takeaway – yes, of course get a degree. Yes, of course develop your knowledge of what you are writing about (you can do this on the job or on your own, but I suggest that job experience outweighs classroom by a long shot). Yes, of course generate some writing samples.

But know this – although you will be an asset if you can code, provide UX, and a host of other technical skills, but at the end of the day, you are a writer. You are a content generator. We all have our area(s) of expertise, and hopefully we are lifelong learners of new skills. Your work will shine brighter than your resume, and your openess will open doors.

Save the true technical knowledge for the SMEs, and learn from them. How technical you are is not tantamount to how well you write technical documentation. Become a strong communicator and all will be well.

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.

How Biased Are Your Release Notes?

~ Susan Kelley ~ 1 Comment

Your Own Thinking Can Make a Big Difference

I should probably start with a primer on Cognitive Bias before accusing anyone of allowing such biases to impact their release-note writing. That’s only fair.

Photo courtesy of Ryan Hafey on Unsplash.

In a nutshell, Cognitive Biases are those thinking patterns that result from the quick mental errors we make when relying on our own brains’ memories to make decisions. These biases arise when our brains try to simplify our very complex worlds. There are a few types of cognitive bias, too, not just one. There’s Self-serving bias, Confirmation bias, anchoring bias, hindsight bias, inattentional bias, and a handful more. It gets pretty complex in our brains, and we’re just trying to sort things out.

These biases are unconscious, meaning we don’t intend to apply them, and yet we do. The good news is, we can take steps to learn new ways of thinking, so as not to mess things up too badly with all of this brain bias. Whew, right?

Now that we’ve established a basic taxonomy, let’s dive in to how cognitive bias may (or may not) be creeping in to things like your technical writing. It’s not just in your release notes; that was just clickbait. But sure, bias can permeate your release notes and nearly any other part of your documentation. (Probably not code snippets, but I won’t split hairs.)

Writers and designers must recognize their own biases so that they can leave them behind when planning. Acknowledging sets of biases helps to shelve the impulse to draft documentation that is shaped by what they already know, assets they bring to the table, or assumptions they make about experience levels.

Let’s start with Self-serving bias. How might this little bug creep its way in to your otherwise beautiful and purposeful prose?

This bias is essentially when we attribute success to our own skills, but failures to outside factors. In our writing, this can appear when we imply that by default, software malfunctions are based in user error. Rather than allowing for a host of other factors, often our writing recommends checklist items that are user-centric rather than system-focused. While it’s true that there are countless ways that users can mess up our well-designed interfaces, there are likewise plenty of points of failure in our programs. Time to ‘fess up.

Confirmation bias can be just as damaging, wherein as writers we craft and process information that merely reinforces what we already believe to be true. While this approach is largely unintended, it often ignores inconsistency in our own writing. We tend to read and review our own documentation as though it is error-free, both from a process perspective and a grammatical-syntactical one. That’s just illogical. And yet, we persist. The need for collaborative peer-review is huge, as even the very best, most detail-oriented writers will make a typo that remains uncaught by grammar software. Humans are the only substitute, and always will be.

We write anchoring bias into our documentation all too often. This bias causes us, frail humans that we are, to rely mostly on the first information we are given, despite follow-up clarification. If we read first that a release was created by a team of ten, but then later learn that it is being developed by a team of seven, we are impressed by the team of seven because they are doing exceptional work. Now, it may be the case that when the ten-member team was working on it, three of them had very little to do. Yet, we anchor our thinking in the number ten, and set our expectations accordingly.

The notion that we “knew it all along” is the primary component of hindsight bias. We didn’t actually know anything, but somehow, we had a hunch, and if the hunch works out, then we confirm the heck out of it and say we saw it coming.

This can happen all too often when we revise our technical writing, jumping to an outcome we “saw coming,” which causes us to edit, overlook, or wipe out steps on the path to getting there. We sometimes become so familiar with the peccadilloes of some processes that we only selectively choose what information to include, and that’s a problem.

Inattentional bias is also known as inattentional “blindness,” and it’s a real doozy when it comes to technical writing, believe it or not. It is the basic failure to notice something that is otherwise fully visible, because you’re too focused on the task at hand. Sound familiar? Indeed. Our writing can get all sorts of messed up when we write a process document, say an installation guide, and don’t pause to note things that can go wrong, exceptions to the rule, and any number of tiny things that can (and indeed might) occur along the way. What to do when an error message pops up? What if login credentials are missing? System timeout? Sure, there are plenty of opportunities for us to drop these into our doc, and many times we do, but I saved this for last because – this will not surprise anyone who knows me – in order to overcome this particular bias, all you need do is become best buddies with your QA person. Legit. I recommend kicking the proverbial tires of your software alongside your QA buddy to see how often you get a “flag on the play.” That will grab you by the lapels and wake you up from the inattention, for real.

Your users will thank you if you learn, acknowledge, and overcome these biases when you write. Is it easy? Not really. Is it necessary? I’d say so. As my Carnegie Mellon mentor told me more than once, and I’ve lived by these words for my whole career: “Nothing is impossible; it just takes time.”

Take time with your writing, and you’ll soon be bias-free.