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

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.

Getting SMART in 2022

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.

Are You a User Advocate? You Should Be.

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.

Compelling and Complete: How to Write Smart API Documentation

Photo by Firmbee.com on Unsplash

Connected web services are the meat and potatoes of the application world today, and providers have to work hard to ensure use and adoption.

Developers are looking for APIs that are easy-to-learn and that perform as they expect them to. Well-written documentation do everything from educating users to attracting developers to start new projects with what you offer. But how do you accomplish that well-written documentation? It’s not as simple as a user manual used to be, but not as complex as designing a whole new website, either.

Technical writers and content strategists who understand the purpose and goal of excellent API documentation are few and far between (but growing!) so here are a few suggestions to ensure that the API doc you write is best-in-class.

Tell the story.

Tech doc gets a bad rap for being dry and merely focused on the functional. When you’re working to drive adoption of an API, it’s key to start with the story. Consider how adopters and users plan to interact with your software, what their goals are – also what your goals are for them, and how you want them to approach the tools.

A prime example of some pretty amazing API doc (according to developers who say so) is Twilio.

Twilio landing page

Just look at that thing of beauty. A Confluence-based setup, this doc offers the story right up front. What does it do? “Power its platform for communications.” Bingo. Then, for new users, “What is a REST API, anyway?” Super smart. This approach leaves very little to chance. And by using Confluence as the basis, that handy-dandy left nav is right there, just waiting to be accessed.

Your story doesn’t do much, though, unless you:

Offer a clear start.

Twilio gets this right again. See the first selection after “What is a REST API, anyway?” Right there.

Twilio API Documentation

Twilio offers a base-level explanation, followed by the opportunity to jump right in. Offering code snips, links to a trial account – it’s all right there, easy to spot for new adopters, potential clients, and even users who have been there before by offering the “Twilio Console.” It is so seamlessly integrated that it feels like you are already a client!

Design the architecture for humans.

Here’s where to avoid mechanical, dry, boring documentation. It’s reasonable to expect that lots of folks will interact with your product primarily at the documentation level. Why bore them here?

Twitter’s API doc nails this and then some.

Twitter API documentation

No one who happens upon this page will feel as though they are greeted with robotic, poorly-planned text. This is written for human consumers with real application goals. “Measure Tweet performance: Build a simple tool…” Naturally, everyone will be enticed by the simplicity. And offering a tutorial? Perfect. This is where developers can come to learn what they need and avoid fluff and jargon.

Don’t be anything less than all-inclusive.

It’s flummoxing to arrive at what you hope to be comprehensive documentation only to find that it isn’t! Document everything, document it thoroughly, and document it well. Look, if someone doesn’t need it, they won’t read the extra, but if it’s missing? That’s just deadly.

Look at how smoothly GitHub handles this:

GitHub API documentation sample

Again, a Confluence-based (or inspired, at least) instance, GitHub organizes everything but the kitchen sink in the list of guides in the navigation panel. All of a user’s questions are answered, or referenced, in that panel. Quick start guides? Check. Building / installation? Check. Each of those navigation titles heads to a page with more information, labeled and cross-tabbed. It’s dream doc.

Highlight learning opportunities.

Never miss a chance to teach. Never. The more your users know and understand, the better you are and the fewer help requests you’ll field. Back to Twilio for an excellent sample:

Twilio API documentation

Products: API docs, quickstarts, and tutorials. All right there in the left nav, with a nicely-organized set of tools to learn. Sweet. It would be virtually impossible for someone to NOT find what they need to learn here. Chances are good that by offering both Quick Start guides and tutorials, all that a developer needs to ramp up is right there for the taking.

And finally, perhaps the most important of all:

Update everything, all the time.

Keeping doc up-to-date is a challenge, I know. Resources are stretched thin, writers work on multiple platforms and products. It’s the same old story. But here’s the thing: if your doc is out of date, then the perception is that your product is as well. The literal only way to ensure adoption and use is to stay on top of the docs. Even if you are sure that users are only reading 1/3 of them, it’s still imperative to head back in and troubleshoot, revise, and update consistently.

If you want people to adopt, you must update.

(I think I’ll use that as my next motto!)

Happy API Writing, fellow tech writers. Do it well, and you’ll rarely be thanked. But do it poorly, and you will suffer great pain.

I wish you well on your API journey. It’s sure to take you far.

Integration. It’s Where it’s At.

Photo Credit: Klim Musalimov

Integration.

Integrated. Technical. Communication.

More exciting than you think. Unless you are already a technical writer, and in that case you were already excited by the idea. Integrated Technical Writing is what folks who decided to call themselves “Content Strategists” have been yearning for all these years.

Yes, I’ve been known to lament that pretty much anyone can slap that label on and prance about calling themselves a content strategist, and it’s true. But if you can find a company whose position is fair and realistic, then integrating content and communication really is that strategy. And it’s fantastic.

I am with a company now, writing proposals for contracts with the government, local, state, and federal, and we GET IT. We totally get it.

I have embraced technical, marketing, and promotional collateral in such a way that I legitimately just put a woman in a sweet yoga pose on the front page of a proposal for the Department of Information Technology for the state where I work. Yes, indeedy. And the tag line is: “She’s flexible, but our standards aren’t.” It’s amazing. And we are going to win a $30 million contract as a result.

We are going to win it because our technical expertise is incredible, yes, but also because we wrote a top-notch proposal that sings marketing through and through.

Integrated Technical Communications has the key language built in:

It integrates the technical componentry with the Communication that needs to be done to sell. And selling is everything. If you cannot learn to operate the machine, the machine is useless.

The US Department of Labor Statistics will tell you how valuable technical writers are. Now go show the labor pool how valuable your creativity is in doing it.

Sharpen your pencil. Your black or yellow or blue or green pencil. Your integrated pencil. Learn the 5 Ws of online help. Learn the tools of the trade and some design principles. But importantly, learn how they all fit together and have fun blending and blending.

Integration is not just for populations and it isn’t a battle, that’s for sure.

It’s logical and it works, and NOW you can be a content strategist.

You got the “D”?

Photo by Mark Claus on Unsplash

No matter what size your company is, or how well-known, I can assure you, every opportunity grasped or missed is the direct, straight-line result of a decision made or a decision delayed.

At lots of companies, decisions get stuck in a pipeline of waiting, approval, hemming and hawing, and sometimes they just die on a vine of withering that is just plain sad to see. Call it bureaucracy, call it checks and balances, call it whatever you like, but it is the companies that are agile, that pivot quickly (stop me if I venture too far into buzz words here, but they caught on for a reason) that survive and even thrive to defeat the others.

Making good decisions, and making them quickly, are the shining coins of successful businesses.

So why is a tech writer posting anything about them? I thought you’d never ask! You see, technical writing has ventured into the deep, lush forest of what now has the lovely, shiny name of “Product Operations” at some of those agile, savvy businesses. Those smart folks took a look around and figured out that the smart folks typing away were…wait for it…learning.

Yes, indeed. And they were right.

We writers have been busy doing, you guessed it, reading. We actually read the stuff we write, believe it or not, and some of it seeps in and we understand it. So when it came time to clear the bottlenecks of business, it sort of made sense to turn to the technical writers who’ve been sitting there reading and writing everything from user guides to employee handbooks all these years and ask them for some insight.

Some of us agreed to offer an opinion or two, and Product Operations was born.

One of the repeated mantras, week in and week out, that I offered to my teams in this process was:

If you oppose, you must propose.

Yep – learn it, commit it to memory. Take it to your teams. Feel free to swipe it. I think I stole it from someone else, and I’m not giving them credit here, so you don’t even have to say you nicked it from me, you can just take it and use it and hog all the credit. (See if it gets you a bit of a promotion or a raise. That’d be nice.)

What it means is, you can point out where something goes wrong – a process, a system, a way of doing things. Go ahead and say it doesn’t work. But then – you have to pony up a way to fix it. We may not use that way, but we won’t ditch it right out of the gate. The most important thing is, you can’t just complain. If you don’t have some sort of solution in mind, even a solution that, in the end, doesn’t fit, you have to keep your trap shut. Don’t point out the flaw until you’ve conjured up a workaround. Even a bad workaround.

A less-than-great decision executed quickly is usually better than no decision executed, or a good decision executed slowly. I mean, a bad decision is going to be a bad decision no matter what. But if you have a brilliant idea but it takes you five years to execute on it, do you really think it was worth it? You can tweak and modify as you go if you just get out of the gate. This is not cutting your bangs we’re talking about here, and even if it was, they’ll grow back. Usually we are talking about developing a new software program or implementing meeting-free Tuesdays. Start building Rome right away. By the time you get the blueprints made, you’ll find the perfect bricklayer, I assure you.

Start mixing mortar.

Right there, that’s the trick. Pick up a stick, or a shovel, or whatever the implement is, and choose. It’s just mortar. You can’t stir it once it dries. So, begin making decisions on a small scale in order to bring about success. As my grandmother once told me, everything can be fixed except death.

I think she might have been exaggerating a bit, so I don’t take it quite that far, but I have determined as a writer that until I hit “send” or “publish,” that I can just decide to write, I can move words around, I can float ideas and concepts, and that to do so is never bad.

In the mode of Product Operations, I started looking at things like information architecture, content strategy, and the blend of systems as a necessary way to get decisions made.

Lo and behold, it worked.

My team began to look at the gaps in our processes and realized that although we each knew what to do when there was a software outage, we each knew what to do when we had to deliver “less than positive” news to a partner or affiliate, we had never concretized that anywhere. So, off we went to create an “Incident Management Guide.”

Similarly, although we had our system down cold for how to manage time and processes in-house, we realized that if a significant part of our team left by, say, taking new opportunities with other companies, the knowledge vacuum would be fierce. The amount of just “stuff” we carried around in our brains about the day-to-day that kept the job pleasant and smooth was astonishing. So we set out to make it a thing. This was despite our tendency as a crew to just be renegade in our approach to daily office behavior, where a meeting was just as likely to be over coffee as it was to be in a conference room. Suddenly, processes and procedures were born.

Some decisions matter, some don’t.

All of this is to say, throughout my years (and they are numerous) I have found that there’s a certain transition from small operation to large, from laid back attitude to not, and back again, that says you somehow gotta put some stuff in writing even when you are pretty sure you don’t. It just makes life easier when you deputize people to have The “D” and to turnaround that decision more easily because they know they can. To build a team with that mojo because it says in a manual (online or in print, with chill or without – you do you) that they can. We built a very nifty team of people, and then we were really able to get stuff done on a big scale by saying, “here’s how we get stuff done.”

I’m just pointing out that it makes life easier if you know:

Do you got the “D”?

Dear Writers, Please Fail to Succeed

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

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

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

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

So on to writing…

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

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

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

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

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

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

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

Making Meaning

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

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

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

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

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

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

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

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

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

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

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

I couldn’t help but chuckle to myself.

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

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

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

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

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

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

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

Image result for artificial intelligence

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

 

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

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

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

Neural-Network-640x360

 

 

 

What to Do When Your Documentation Speaks… Literally

 

megaphones

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

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

Allow me.

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

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

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

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

Eureka!

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

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

It seems I have opened an oyster of sorts.oyster

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