Writing

Why the Humanities Matter in STEM

~ Susan Kelley ~ Leave a comment

Photo credit: Prateek Katyal, 2023.

A 2017 article in the Washington Post discussed how now, in the age of big data and STEM (Science, Technology, Engineering, and Mathematics), liberal arts and humanities degrees are perceived as far less valuable in the marketplace. I saw the same opinion held strong at both universities where I taught English. Many, many students believed wholeheartedly that the only thing they could do with a degree in English is teach.

I was hard-pressed to convince them otherwise since I was, in fact, teaching.

The Post article goes on to argue, however, for abundant evidence that humanities and liberal arts degrees are far from useless.

When I started graduate school in 2007 at university that beautifully balances the arts and sciences (shout out to you, Carnegie Mellon!), my advisor recommended I take “the Rhetoric of Science.” I meekly informed her that I wasn’t really into science. I thought it would be a bad fit, that I would not fare well and my resulting grade would reveal my lack of interest. She pressed, saying there was a great deal to learn in the class and that it wasn’t “scienc-ey.”

She was absolutely right. I was fascinated from the start. The course focused on science as argument, science as rebuttal, but most of all science as persuasive tool. Or, at least the persuasiveness came from how we talk and write about science. My seminar paper, one of which I remain proud, was titled: “The Slut Shot. Girls, Gardasil, and Godliness.” I got an A in the class, but more importantly I learned the fortified connection between language and science.

The National Academies of Sciences, Engineering, and Medicine urges a return to a broader conception of how to prepare students for a career in STEM. Arguing that the hyper-focus on specialization in college curricula is doing more harm than good, they argue that broad-based knowledge and examination of the humanities leads to better scientist. There is certainly the goal among academics to make students more employable upon graduation, and yet there is consensus that exposure to humanities is a net benefit.

The challenge is that there’s no data. Or, limited data anyway. The value of an Art History course or a Poetry Workshop at university is hard to measure against the quantifiable exam scores often produced in a Chemistry or Statistics class.

In a weak economy, it’s easy to point to certifications and licenses over the emotional intelligence gained by reading Fitzgerald or Dickinson. We find, though, that students (and later employees) who rely wholly on the confidence that science and technology provide answers, viewing it with an uncritical belief that solutions to all things lie in the technology – well, those beliefs are coming up short. Adherence to the power of science as the ultimate truth provides little guidance in the realm of real-world experiences.

In short, not all problems are tidy ones.

After all, being able to communicate scientific findings is the icing on the cake. We don’t get very far if we have results but do not know how to evangelize them.

In American universities right now, fewer than 5% of students major in the humanities. We’ve told them that’s no way to get a job. The more we learn about Sophocles, Plato, Kant, Freud, Welty, and others, the more prepared we are to take on life’s (and work’s) greatest challenges. It is precisely because the humanities are subversive that we need to keep them at the heart of the curriculum. Philosophical, literary, and even spiritual works are what pick at the underpinnings of every political, technological, and scientific belief.

While science clarifies and distills and teaches us a great deal about ourselves, the humanities remind us how easily we are fooled by science. The humanities remind us that although we are all humans, humans are each unique. Humans are unpredictable. Science is about answers and the humanities are about questions. Science is the what and the humanities are the why.

If we do our jobs well in the humanities, we will have generations to come of thinkers who question science, technology, engineering, and math.

And that is as it should be.

I welcome discussion about this or any other topic. I am happy to engage via comment or reply. Thanks for reading.

Advertisement

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.

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.

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.

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.

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.

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.

Integration. It’s Where it’s At.

~ Susan Kelley ~ 2 Comments
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”?

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