Will Write for Metamucil

I am ill equipped to write for an emerging segment of the marketplace. But that doesn't mean I'm used up like a worn-out number two pencil stub (my favorite simile these days). But it does mean that I need to reevaluate where and how I add value.

Hughes, Michael A. User Assistance (2008). Articles>Documentation>Technical Writing>Multimedia

The Sacred Cow Blocking the Road

When product teams ask technical writers to document software products, writers usually start their projects by analyzing the tasks users will perform when working with them. A task analysis generates a list of procedures—plus the supporting information users need to follow them—and eventually results in a document in which sequentially numbered instructions are the dominant type of information—neatly organized under user-centered task headings and preceded by enabling knowledge. It sounds ideal, classical even. The problem? Users don’t read procedures.

Hughes, Michael A. UXmatters (2007). Articles>User Experience>Documentation>Technical Writing

Placing Value on User Assistance

User assistance writers are often the Rodney Dangerfields of the UX world, bemoaning the fact that we don’t get any respect. I think the real problem is that user assistance folks are not particularly good at communicating the ways in which we add value to an enterprise. This column explores two models that show how user assistance adds value and how we can communicate that value to those who pay our salaries—something I would like to encourage other user assistance writers to do.

Hughes, Michael A. UXmatters (2008). Articles>Documentation>Technical Writing>Workplace

Technical Writer as Playwright

Help is read in snippets. Avoid ambiguous parts of speech and make each snippet a good little play that you can easily imagine being acted out on stage.

Hughes, Michael A. User Assistance (2009). Articles>Writing>Technical Writing

Surviving Tough Times as a User Assistance Writer

Early in my technical communication management career—more than twenty years ago—I made this observation: “I can produce a manual that users won’t read for $50,000, or I can produce a manual that users won’t read for $5,000.” My point was that, until we started writing manuals users actually read, the $5,000 option was the better business strategy. But now, to heck with producing manuals users won’t read. This new world of post-2008 meltdown has changed the game. We must now write manuals users will read, and we must write them for $5,000.

Hughes, Michael A. UXmatters (2009). Articles>Writing>Technical Writing

Progressive User Adoption

User assistance can add value to a product or Web service’s business model by influencing how deeply users adopt new features or services. As more products employ pay-as-you-go models like that of SaaS (Software as a Service), the contribution user assistance makes becomes increasingly more important.

Hughes, Michael A. UXmatters (2009). Articles>Documentation>User Centered Design>Help

How to Improve the UI--Really!

A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience.

Hughes, Michael A. User Assistance (2009). Articles>User Interface>Documentation>Technical Writing

Architecting User Assistance Topics for Reuse: Case Examples in DITA

In this column, I’ll review what user assistance architects mean by reuse and what its benefits can be. I’ll then describe some different scenarios for reuse and offer guidelines that user assistance architects and information developers can follow. My examples show how DITA (Darwin Information Typing Architecture) can be an effective reuse framework. But the principles I discuss go beyond DITA, and you can apply them to any structured information framework or toolset.

Hughes, Michael A. UXmatters (2009). Articles>Content Management>Documentation>DITA

Online vs. On-Line

This isn't a discussion of hyphenated vs. not hyphenated. It examines the difference between putting a PDF file on the Internet (what I call an on-line document) and having a truly electronic Web presence for that content (what I call an online document). Unfortunately, the two often get bundled together.

Hughes, Michael A. User Assistance (2009). Articles>Web Design>Publishing>Adobe Acrobat

Cop vs. Consultant

Pay attention to the legal requirements and translatability issues, not only in your own documents, but in the documents of other groups like marketing and engineering. It's an area where we add value.

Hughes, Michael A. User Assistance (2009). Articles>Intellectual Property>Trademark>Technical Writing

STC: Quo Vadis?

I need to figure out where I am with all the STC stuff going on, and blogging will help my introspection. Also, it will let me share with you some of the background and complexity that surround the current state of affairs with STC. My e-mail tag line reads "Anyone who is sure of the answer doesn't understand the question," and this blog is an invitation to join me in understanding how we got here, where we are, and where I think we need to go.

Hughes, Michael A. User Assistance (2009). Articles>TC>Planning>STC

Use Cases for User Assistance Writers

Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it. SGML is a good example. It seemed like a great idea, but for a long time, had trouble getting traction in the general tool space. Then it started showing up at technical communication conferences wearing a name badge that said, “Hi, my name is DITA,” and suddenly, it’s a hit!

Hughes, Michael A. UXmatters (2009). Articles>Documentation>XML>DITA

Screen Shots in Documentation

Just as I would with words, I'll cut out the obvious and whatever does not add value. I prefer an additive approach (put it in only when the words seem inadequate) over a subtractive approach (take it out if it seems superfluous). In other words, I'll be more open to screen shots in the future, but they have to work themselves into the document, not just be their by entitlement until expelled.

Hughes, Michael A. User Assistance (2009). Articles>Documentation>Technical Illustration>Screen Captures

Talk Your Walk

We confuse people when there is a disconnect between our stated beliefs and our theories in use. When managers say they demand teamwork but evaluate employees based on individual accomplishments, they do a disservice to the person who puts the team's overall needs ahead of his or her specific goals. That person gets punished for believing what the boss said and acting on it. But don't be so quick to blame the disconnect on your behavior--It could be you are reciting scripts that describe what you think you should do.

Hughes, Michael A. User Assistance (2009). Articles>Writing>Theory>Professionalism

Comic Relief

As part of a project I'm working on, we are going to develop a comic-style collection of user scenarios to help communicate best practices around a security service we are offering.

Hughes, Michael A. User Assistance (2009). Articles>User Centered Design>Technical Illustration>Personas

Visual Methods of Communicating Structure, Relationship, and Flow

Many of us are more comfortable communicating in words than in pictures. For example, user assistance writers are by nature and training writers, so they understand words and are adept at using word processing and publishing tools. Writers use lexicentric tools not only for creating and delivering content, but also as cognitive tools—that is, tools that help them think more clearly and efficiently. Thus, a user assistance writer might create a user-task matrix or take advantage of a word processor’s outline view when creating or evaluating a document’s structure.

Hughes, Michael A. UXmatters (2009). Articles>Graphic Design>Technical Illustration>Workflow

Reverse Engineering SIGs

STC SIGs are like areas where outside professions insert specialized instances of their expertise into our profession. But what if we could reverse that gateway? Our SIGs could be an excellent outreach channel to market our specialized knowledge into those other professions.

Hughes, Michael A. User Assistance (2009). Articles>TC>Community Building>STC

Dip Management

We go from one moment being very proficient with our current tool or technology to being pretty stupid with a new one. So the basic question every user ends up answering is Was the improvement labeled "B" worth the pain and humiliation labeled "A?"

Hughes, Michael A. User Assistance (2009). Articles>Technology>User Experience