Course Preview: UX Writing for Tech Writers

Course Preview: UX Writing for Tech Writers

It’s time technical audiences got some UX writing love. Are you a technical writer? Are you looking for ways to level up your work? Are you interested in UX writing?…

Patrick Stafford
March 3, 2021


It’s time technical audiences got some UX writing love.

Are you a technical writer? Are you looking for ways to level up your work? Are you interested in UX writing?

If you answered yes to all of the above, you’re in the right place. Welcome. Our new course is made to bring tech writers like you the UX tools and strategies you need to get ahead of the curve, flex new skills, and become a user-centered technical writer.

“Discover the incredible amount of impact you have, how to bring UX principles into documentation, the basics of UX writing,  as well as a ton of other tools, tricks, and best practices for writing human-centered technical content.”

— Dave Connis, Sr. Documentation & UX Writer


Quick Links

Frequently Asked Questions

Lesson 1: Technical & UX writing compared

Lesson 2: How good UX affects documentation

Lesson 3: Technical UX writing principles


LESSON 1: TECHNICAL & UX WRITING COMPARED

Let’s acknowledge that there’s a growing overlap between technical writing and user experience (UX) writing. Technical writers are expected to understand what it means to be user-centered, efficient, clear, and focused on task completion. Many companies already consider their tech writers to be UX writers, and UX writers often write for technical audiences. There’s a spectrum between the two writing roles, not a hard line.

The goal of this course is to provide tech writers with UX and user-centered tools and frameworks to help them design and advocate for more user-focused experiences.

After completing the course as a technical writer, you’ll know how to:

  • Help your users achieve goals and complete tasks faster and more simply by applying principles from UX writing
  • Think of your documentation as a user-focused product
  • Understand how to write for interfaces
  • Learn how to bring meaningful design methods to your doc design and development

Let’s start with a rough comparison of each role. Differentiating between the two will help us articulate how to move the roles closer together.

What’s the same

At the most basic level, both types of writing help people to get stuff done using software or computers. Both types of writers must understand:

  • Users’ goals
  • Users’ specific characteristics, micro-culture, language, and common terminology
  • The app, software, or technical tool the audience is using
  • The mechanics of writing directly, clearly, and succinctly

Both use language-based principles like information hierarchy and architecture, preferred language, content formats, logical learning, and task flows.

What might be different

Because writing for software ranges from very simple apps to highly complex systems, the line between tech writing and UX writing isn’t solid. It’s blurry and evolving, so imagine each sentence below with a “generally” or an “often” in front of it.

  • Technical writers mostly write for highly technical audiences who use complex tools. UX writers often write for consumer apps and sites that are less complex.
  • Tech docs have fewer length constraints. UX writing, especially interface writing, tends to require keeping everything short.
  • Technical documentation often lives outside a product. UX writing most often guides users from inside a product.

Examples of content outputs

Let’s take a quick look at what each role might write day to day, and what’s shared between the two.

Technical writers UX writers Both
API reference material Sign-up, setup, and onboarding copy for apps and sites Business-to-business (B2B) interface text such as enterprise apps and tools
Hardware manuals Interface guidance including instruction text, app errors, alerts, notifications, buttons, labels, toggles, lists, modals, and search functions Style guides for teams
Server maintenance guides and other system administration documentation Content-first design mockups Troubleshooting guides
Documentation for platform-level infrastructure tools and systems Consumer-facing product names, feature descriptions, and marketing copy Metadata
Security protocols and methods Content systems to align with design systems Taxonomies
Walkthroughs and tutorials Voice dialogs for mobile apps Information architectures
Software development kits (SDKs) Error messages
Internal reference material Software update release notes

The hybrid writer

Because software, apps, websites, and voice experiences continue to evolve beyond these simplified definitions, we’ll leap ahead a bit and introduce a new term: technical UX writer.

This new term will let us refer to “a technical writer who makes extensive use of UX writing principles and approaches” in a much shorter, easier way. No one outside of this course will recognize a whole new field or discipline—it’s just shorthand for us to use together in this course.


LESSON 2: HOW GOOD UX AFFECTS DOCUMENTATION

Part of the power of being a technical UX writer comes from understanding and accepting that documentation is more than just step-by-step instructions. Tech docs support products, but the truth is—they often are the product. A technical customer’s most extensive interaction with a company often happens with the documentation.

Imagine there’s a spectrum for documentation: at one end, we have static, traditional docs that provide a lot of information, but don’t take user needs or flows into account. At the other end, we have user-centered docs that align with user needs, goals, and intentions.

This Sun Microsystems screen is a typical example of  documentation that provides info, but isn’t user-centered. It’s a jumble of concept, task, and reference info that the user must parse through to complete a task.

Source: Java ME Platform Software Development Kit (SDK) via Oracle

In the screen capture you can see:

  • Table of contents to the left
  • Content pane that contains some basic HTML formatting
  • Table on the right

In this example, we might say the common standard has been achieved. Done. Move on. Let them go to Stack Overflow if they need more.

A developer might go to the docs, get what they need, and then get out, thinking nothing of the “experience.” That’s not terrible, but it falls short of the goal to support technical users in a deeper, more intentional way that aims to proactively help users.

Consider the following API documentation from Stripe:

Source: Stripe documentation

First, note that both of the example docs shown are for payment APIs. The first doc example is a static image, but the second doc is an animated GIF that guides users through a series of steps that match how they might complete a task.The first experience has no interactivity. The explanation is almost stark. The second is rich and dynamic, giving users more than just the minimum information they need. The Stripe documentation is designed with the user in mind and a focus on user success.

Good UX in documentation has impact and value 

The value to Stripe goes far beyond business outcomes like decreased support calls and churn. They’re also building value like:

  • Developer respect, loyalty, and trust. The idea that developers and technical audiences only care about getting the information they need doesn’t stand up under the Stripe docs. If you ask developers what they think are good docs, many will mention Stripe—even if they don’t use the Stripe product. No one is going to mention the first API example from Sun Microsystems. In fact, they probably won’t even remember it after they leave work. When we put care into our docs, it shows. Developer trust impacts the business in concrete ways.
  • Brand awareness. Companies spend hundreds of thousands of dollars trying to buy brand awareness through paid ads, campaigns, content marketing, and so on. Though this sort of awareness has its place, Stripe has built awareness and reputation by simply creating an amazing experience that people (users) want to talk about and, more importantly, that they respect. It’s not enough to simply tell people you have value. It’s much more effective to deliver it with a delightful experience.

The bottom line? Good user experience design adds value to products of any kind—including documentation. In the remainder of the course, we’ll focus on how to bring good UX to your documentation and writing processes.


LESSON 3: TECHNICAL UX WRITING PRINCIPLES 

Now that we’ve covered the basics on the similarities and potential differences in UX and technical writing, let’s start with the focused principles that guide UX writing. In this lesson, we’ll introduce the principles and then translate them into technical UX writing principles.

Right content, right user, right time

Show the right content to the right audience at the right time. Good UX writing isn’t just about the words. It’s about expediting problem solving. The goal is to help users get to the best solution wherever they’re at in their journey.

Here’s how we might translate this principle for technical writing:

The right content isn’t bound to documentation—put it wherever users need it most. The Nielsen Norman Group (NN/g) describes 2 types of guidance: Reactive and Proactive. Users initiate reactive guidance. They must go and seek it out. Reference documentation falls under this definition. Proactive guidance doesn’t wait for users to seek it. It’s predictive. It aims to help the user before they know they need it. Examples of this type of guidance include tooltips, microcopy, and instruction text inside a product interface.

Think like a friend, talk like a coach

If you were explaining a complex concept to a friend, you’d explain as patiently and simply as possible. You’d talk to them as if you’re in their corner. You’d do your best to reassure them and build trust. You’d work hard to keep the friendship solid and help your buddy out. UX writers approach their words in this human-centered way. It’s a practical application of empathy.

Think of a user coming to your docs like an athlete coming to a coach. Athletes work with coaches to learn how to improve their performance and achieve their goals. In that sort of coaching relationship, being friends is less important than an effective, professional relationship that achieves results. However, that doesn’t mean you can’t be friendly or should act like you don’t care. Because, of course, you care. You want users to succeed. A coach that’s unsympathetic likely won’t have many people coming to them for help. But, the point of a coach is to be strategic, knowledgeable, and clear, so that the athlete can achieve the results they want. You’re not helping a buddy, you’re improving their performance.

Think about documentation like a friend, first considering how to explain, structure, and guide in an empathetic, human-centered way, then write with the knowledge and clarity of a coach.

Reduce friction at every step to guide new and advanced users alike

UX writers lead users through screen-based experiences anticipating potential questions, eliminating doubt and worry, and providing necessary context and info. The goal is to always keep the user moving forward with confidence.

Because technical users are tough, persevering, smart, and ridiculously resourceful, technical writing is sometimes at risk of taking a “less-is-best,” almost minimalist approach to providing assistance. But, a technical user’s ability to figure things out on their own shouldn’t impact how far we go to help them succeed. Users will succeed at higher rates if we’re willing to go the extra mile with guidance, helping to develop mental models and move users along their path.

If information is useful for new or less-familiar users to succeed with your product, include it. Don’t worry about coddling or talking down to users. Let advanced users skip what they don’t need. 

To be clear, if you’re writing for a developer persona, we don’t mean that you should explain what JavaScript or CSS is. Your persona defines the range of what’s included as “information required to be successful with your product.”

Communicate with clarity

UX writers articulate the voice, choose the terms, establish content hierarchy, and write the instructions, messages, and responses for any given product.

They use plain language. They write in uncomplicated terms using customer language—not corporate speak or unfamiliar jargon—as they explain a product’s functions and features. If there is an unfamiliar word, the UX writer must define it and use it in context to ease comprehension and build a mental model.

Readability, the ability to understand text easily, is also important. Creating scannable content with good information architecture and hierarchy are basic clarity-making tools. We know there’s always a tension between clarity and concision. We always want to get rid of excess text, but never want to sacrifice clarity to achieve brevity.

Tech writers use these tools, too.

Technical writers use plain and customer-centric language—not corporate speak or unfamiliar jargon—as they explain product functions and features.

Just like UX writing, readability (the ability to understand text easily) is incredibly important.

Proactively prevent errors and confusion

Because UX writers are always looking for ways to improve the user experience, they’re mindful of the hundreds of things that can get in the way of user success. To help users they:

  • Reduce cognitive load (how hard a user has to think about something before it “makes sense”)
  • Ensure logical task flows and user progression throughout an experience
  • Prevent user problems and user education failures

Technical writers have a similar responsibility. They must:

  • Create ways to find answers that don’t exhaust users
  • Ensure findability and searchability
  • Prevent in-depth troubleshooting that might require multiple steps and actions

Similar to “Communicate with clarity,” this principle, though applied in different ways, is shared by both disciplines. Both docs and the product need proactive approaches to reducing friction.


FREQUENTLY ASKED QUESTIONS

How long is the course? Is it self-paced? 

Time estimates fall around 20-40 hours of study and practice work for this course depending on your speed. There are 5 units in the course. Each unit is broken down into a series of 3-6 lessons with practice quizzes and reviews along the way. To be certified, you must receive a passing score on the final project and final exam.

This course is designed to fit around your schedule; lessons are available on-demand at any time. There is no live instruction, so you’re free to study at your own pace.

Who is the course for? What are the prerequisites? 

This course is made with technical writers in mind. If you’re a tech writer who’s interested in applying UX best practices to your work, this course is for you. If you’re a tech writer who is interested in moving into UX writing full-time, consider UX Writing Fundamentals.

Prerequisites:

  • A computer with the latest version of Chrome
  • A broadband internet connection
  • Fluent English comprehension and writing proficiency
  • Working technical writing knowledge
  • A love for writing, tech, and good communication with humans

How does this course differ from UX Writing Fundamentals?

The UX Writing Fundamentals course is designed for writers who are new to working as part of a design team. Perfect for junior writers looking to make a switch, or writers transitioning from adjacent roles who want to take on UX writing full time.

UX Writing for Technical Writers takes your existing technical writing knowledge and builds on it. You’ll learn to apply UX writing best practices to your work as a tech writer plus how to write for UI components. Designed for writers who want to be competent in both disciplines.

Is there a professional certification upon course completion?

Yes! If you successfully complete the final project and exam, you’ll walk away with a certificate to showcase your new skills.

Why should I study with UX Writers Collective? 

Unlike other courses out there, our courses are developed by expert UX writers and managers from companies like Google, Intuit, MYOB, Charter Communications, Amazon, and more. Studying with the UX Writers Collective will set you up to succeed at similar tech companies like Apple, Microsoft, Spotify, Shopify, and Netflix.

Already work in tech, but need to hone some world-class writing skills? Are you ready for a fun, creative, and lucrative job?

Come study with us! Our courses provide:

  • A curriculum designed by professional UX writers from the world’s leading companies
  • A solid, career-building foundation in user experience and design writing
  • A Facebook group and a Slack Mentor group exclusively for students
  • Practical, hands-on experience with the opportunity to finish a portfolio-ready project
  • Personalized feedback from instructors on practice work and your final project
  • More than just UX writing skills: the critical knowledge you need to succeed in a UX design team

This blog post is just a very small taste of our course, UX Writing for Technical Writers. If you’re ready to level up your writing, check out the syllabus and sign up!