Month: October 2021

Are You a User Advocate? You Should Be.

~ Susan Kelley ~ Leave a comment

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

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

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

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

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

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

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

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

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

Do these fit well and match my outfit?

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

Advertisement

Compelling and Complete: How to Write Smart API Documentation

~ Susan Kelley ~ Leave a comment
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.

Everyday Words: Keep It Simple

~ Susan Kelley ~ Leave a comment

Otherwise known as “ditch the jargon already.”

I studied writing at Carnegie Mellon University (well, I first studied it in high school and had a teacher who was practically the grand master of Strunk and White, but I’ll get to that later). At CMU, we were indoctrinated into the Erwin Steinberg methodology of Plain Language. Today, that may seem like a simple concept, but I assure you, it wasn’t always that way.

Dr. Steinberg was something of a visionary. There was a time when most, if not all, technical writing was to be drafted in passive voice. It should sound authoritative. Certain. Unfriendly. Passive was the way to go! Professional and technical writing was horrifyingly boring, and that is just the way everyone seemed to like it.

Except they didn’t like it.

Imagine having to read this all day:

“The program will be completed by users only after the messages are received. Emails that have been sent will not be opened upon receipt.”

Are you asleep? I know I am. It’s just awful. And that isn’t even an example full of jargon. Wait for this one:

“Users should redirect their interface from the AWS blockchain system and consider a CMS that works with the UI. It can be discussed in scrum whether the vector graphics will be wired in or whether that is a sandbox item.”

Yeesh. I’m not even sure that makes sense, because I just tossed in all of the jargon that popped into my head. But I assure you, I’ve heard plenty of conversations using that word-spaghetti.

Jargon causes a problem no matter what, because using it runs the risk that your reader won’t understand it. Even seasoned readers don’t know all of the potential terms.

So Erwin Steinberg’s philosophy, the one that he impressed upon the hundreds of students he taught, and the philosophy of legends at Carnegie Mellon was this: write it in plain language.

Presto!

Whether the text you are creating is something you understand quite well or it’s something you are translating for an SME (see what I did there?) – Subject Matter Expert, try to be sure that you simplify. This is not to say that every piece of writing needs to be watered-down. Of course not.

Consider the uses of jargon, and the need for explanation. Moreover, consider the origin. Journalist Allison Linn, writing for the Associated Press, discussed the emergence of the word “solution” in the tech industry. In common parlance, a solution is that which solves something. Easy enough, yes? But in technical jargon, a “solution” is merely a product. Tech companies release solutions.

Marketing took over and created jargon. Along came words like “enterprise,” “experience,” “agility,” “migration,” and a host of others. We now optimize things, we migrate data, and…gasp, we coined the portmanteau “blog” from Web and log, and you have this little project of mine right here.

The difficulty with jargon is that it is used by a subset of people, not the whole group of potential readers.

What Steinberg taught was that messaging, even technical documentation, needed to be accessible. Writers should identify their audiences and write to those. So of course, if the consumers of a given piece of documentation are solely, exclusively tech-familiar end users, and those users will understand the acronym SaaS, then by all means go ahead and toss it in. But by and large, if there is a snowball’s chance that any Tom, Dick, or Mary will get their eyes on the doc, then just write Software as a Service, and follow up with the acronym, willya?

There’s no need to dress up the text. And here’s where my high school English teacher comes in. He loved Strunk and White so much that his mantra was “Omit needless words.” That guy would legitimately write it on every piece of nonfiction prose any student submitted. He taught me the economy of words. He taught me a grave distaste for the word “nice,” demonstrating that it conveyed nothing of value.

Nothing, he said, was “nice.” It could be splendid, lovely, beautiful, tasty, delightful, mediocre, incredible, and a host of other words, but it could not be “nice.” I miss that guy.

The last word on this subject is: edit. Supposedly, (and I scoff at this, but I am pessimistic), Mozart wrote a symphony in a single draft. We are not Mozart. Cut the chaff. Weed out the unnecessary.

Especially if it is jargon.

And After a Hiatus…

~ Susan Kelley ~ 2 Comments

I am really (truly) not a fan of those posts that apologize for when writers take a break from their blog and then assure readers that they will do better, be more faithful, write more – you know the drill.

And yet, here I am, apologizing for a lengthy absence. As if I have any readers left here.

The story goes that I moved from Pittsburgh (my bio still says I live there), and started a new job. That job was cool and it kept me busy, and I thought maybe I would just table the whole tech writing thing. I wasn’t really engaging in tech writing any more, so it made sense.

So, I left this little project alone.

Then, COVID-19 came along and I got laid off. Yeah, bummer, right? I focused more on my writing over at Medium (you can follow me there if you’d like, but it’s vastly different writing than it is here). I took some time to finish my as-yet-unpublished book. I’m still looking for an agent and publisher for that gem.

But after I got a new job, I was in proposal writing. Tech writing-adjacent. Sure, I edited and oversaw proposals in my tech life, but I started as a proposals manager for a small shop. Then I moved on to what I thought was a plum gig working for a friend at the company that brought me to Baltimore, then laid me off. Turns out that wasn’t the best gig, because they were undergoing lots of change.

And now, here I am, a proposal manager, but thanks to some strained workplace relationships, I am not really managing a lot of proposals, but I’m editing, moving things around, and digging in to some other work.

I’m hoping to leverage my smarts and talents to stay here and dig in to Confluence management and shoring up their much needed information architecture, but in the meantime, I will dust off my tech chops and head back to this comfy place.

All two or three readers, and anyone new who stumbles here will be treated to some new insights, a fresh look at how writing about technology dovetails with writing technical services proposals. I can’t give away any trade secrets, of course, or they wouldn’t be secrets. But all in all, I think I still have some good writing to share on this, my professional space instead of over at Medium, my personal platform.

So thanks for letting me take a break, and allowing me space to grow. Go grab a pint and let’s see what happens next.