Error Message Guidelines

Established wisdom holds that good error messages are polite, precise, and constructive. The Web brings a few new guidelines: Make error messages clearly visible, reduce the work required to fix the problem, and educate users along the way.

Nielsen, Jakob. Alertbox (2001). Articles>Writing>Technical Writing>Help

Error Message Guidelines

An error message is text that is displayed to describe a problem that has occurred that is preventing the user or the system from completing a task. The problem could result in data corruption or loss. Other message types include confirmations, warnings, and notifications. The guidelines in this topic are intended to help you write clear error messages that are easy to localize and useful for customers.

Microsoft (2006). Articles>Documentation>Writing>Technical Writing

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

HelpScribe: Great Examples of Technical Writing

Not all manuals are created equal. Some are infused with the character and skill of their creator, and rise above the mere paperweights that line the shelves of used bookstores of small-town USA. Some examples of technical writing are so effective, even enjoyable, that they earn a place in the memory of readers. Here are a few technical writing examples that have earned my admiration.

HelpScribe (2008). Articles>Writing>Technical Writing>Case Studies

The Importance of Technical Writing

Technical writing serves as a bridge between products and users. It is an essential component of the customer experience. Without accurate documentation, users cannot efficiently learn to use the products they've purchased, and will struggle at best.

HelpScribe (2008). Articles>Writing>Technical Writing

When Trust Becomes a Characteristic Flaw in a Project

As hard as it may seem, lesson one of technical writing is to break the rules and contact the end user. Conduct a mini-ethnography. Sit with the users. Call them on the phone. Send them emails. Do not let it get to the point where you feel you must go through the PM to communicate with the end user. As hard and uncomfortable as it may be, the consequences of not talking to the end user can be crippling to your help.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Project Management>Collaboration>Technical Writing

Technology Transfer: An Unparalleled Opportunity for Technical Writing Professionals    

This nation does not effectively transfer expensively acquired knowledge into cost-effective, labor-saving tools and processes.

Roberts, Suzanne S. IEEE PCS (1991). Articles>Knowledge Management>Technical Writing>Technology Transfer

Don’t Let your Product’s Features Become Expensive Flaws

Your product’s unexplained features can turn into costly flaws. This article describes three real-world products with just such “features.” It presents ways you can prevent these feature-to-flaw conversions by improving the User Documentation for your products.

Espresso (2008). Articles>Writing>Technical Writing

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

Giving the Instructions a Fair Shot

We as technical communicators ought to afford each other the courtesy of using each other’s materials when the need arises. As the writers, we know how valuable it can be, and if we don’t use it when the need arises, we’re contributing to the prevalent concept that “no one reads it anyway.” By doing so, we shoot our own profession in the foot.

Gryphon Mountain (2008). Articles>Documentation>Technical Writing

Toward a Post-Technê: Or, Inventing Pedagogies for Professional Writing    

This article examines the concept of technê in relation to situatedness. Technê is conceived as techniques for situating bodies in contexts. Although many theorists and practitioners in technical communication are working from ecological and posthuman perspectives with regard to interface designs, this article argues for extending those perspectives to workplace and classroom situations. Starting from a Heideggerian reading of technê, the article moves toward the concept of post-technê, which remakes pedagogical techniques for writing and inventing in institutional contexts.

Hawk, Byron. TCQ (2004). Articles>Education>Business Communication>Technical Writing

Why Wikis Won't Kill Technical Writing

Many people have predicted that wikis will replace traditional help in the future. Ok, I can buy that. But I've also heard that technical writers will surrender content control to SMEs and users, and will move into other roles such as merely editing wiki content, or switching to programming, training. Sorry. I just can't see that happening. In the world of wikis, technical writers will still be kings of content.

HelpScribe (2008). Articles>Documentation>Technical Writing>Wikis

Structured Authoring for Everyone

Structured authoring isn't just for technical writers. Just about any department in an organization can benefit from it. This article looks at one way of bringing structured authoring to the masses: by adopting the authoring concepts used in an obscure word processor called Yeah Write.

DMN Communications (2009). Articles>Information Design>Technical Writing>XML

What's Your Technical Writing Personality Type?

Because personality has a strong influence on technical writing skills, it may help to take a look at how psychologists categorize personality types.

Haiss, Craig. HelpScribe (2009). Articles>Writing>Technical Writing

How Color Defines Purpose in User Assistance Content

Of all the visual cues in your help interface, color is one of the strongest. Users will recognize and react to the color of each element in your help window before reading a single word of text. Color allows users to determine the purpose of each element on the computer screen. When designing the visual aspect of your help content (via CSS and so on), as well as the help interface itself, be sure to use the same color for objects that share a purpose.

Haiss, Craig. HelpScribe (2009). Articles>Documentation>Technical Writing>Color

Avoid Culturally Specific References

One of the tenets of good technical communication is to avoid culturally specific references, especially if your material is to be translated into other languages. But what’s a culturally specific reference? In simple terms, it’s a word or phrase that has meaning for members of a cultural group, but has limited meaning, no meaning, or some other meaning for people outside that group.

CyberText Consulting (2009). Articles>Writing>International>Technical Writing

Blogging: A Way to Give a Bit More Meaning to Life

I’ve realized that having a blog helps me think more about my professional activities and interactions than I would otherwise. I give them more thought because I think about whether they’re something I can write about.

Gryphon Mountain (2009). Articles>Writing>Technical Writing>Blogging

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

Controlled Language in Technical Writing  

The documentation used in manuals and other technical writing worldwide is predominantly created in English. Though much discussion has been devoted to it in academia and elsewhere for years, technical English continues to be written in a way that is difficult for many people to understand.

Braster, Berry. Multilingual (2009). Articles>Language>Technical Writing>Controlled Vocabulary

Writing Technical Documentation with Sphinx, Paver, and Cog

I've been working on the Python Module of the Week series since March of 2007. During the course of the project, my article style and tool chain have both evolved. I now have a fairly smooth production process in place, so the mechanics of producing a new post don't get in the way of the actual research and writing. Most of the tools are open source, so I thought I would describe the process I go through and how the tools work together.

Hellmann, Doug. O'Reilly and Associates (2009). Articles>Documentation>Software>Technical Writing

Technical Writing and XML: Reconciling Editorial License with Structured Markup

In writing reference material, consistency of organization and presentation is key. If the same information is presented in a consistent order and style throughout the publication or information set, it enhances the readability and usability of the material for the consumer. Ease of use is vital. XML provides a means to assist in the standardization of reference material from both an organizational and a semantic/content-oriented standpoint. Standardization based on structure and content enhances the potential for reuse of the XML-tagged information for both print and electronic delivery.But while there can be a strong relationship between the authoring and editing of content and structured markup, all too often conflicts arise between technical writers and DTD/schema designers and programmers. The perceived need for editorial license and creative freedom by many authors/editors clashes with the need for rigid structure to facilitate ease of programming for markup technologists and programmers. The disagreements are commonly between format and structure, looseness and rigidity, and are often more philosophical than practical.

Rudder, Douglas. IDEAlliance (2004). Articles>Writing>Technical Writing>XML

Syntext Serna and New Trends in XML Content Authoring

Recent trends in XML content authoring demonstrate increasing shift towards advanced reuse patterns and multi-source compound document architectures. This imposes completely new requirements for the XML authoring tools, most of which were originally developed for narrative document authoring and architectures like Docbook or TEI. The key requirement is the ability to provide a single, transparent, directly editable view for such complex documents.

Antonov, Paul. IDEAlliance (2005). Articles>Information Design>Technical Writing>XML

Asking Questions is Key

I think one of the hardest things in technical writing, especially for new hires, is to be assigned to document a product or feature that you know nothing about.

Technically Speaking (2009). Articles>Interviewing>Technical Writing>SMEs

What is a Controlled Language or Simplified Technical English?

The main objective of a controlled language is to make technical text easy to understand. Simplified Technical English standardizes vocabulary and style, aiming to improve consistency, eliminate ambiguity and reduce complexity. It also provides objective criteria for quality control. Simplified Technical English includes a general dictionary and a set of writing rules. In addition to the general vocabulary, companies can define their own Technical Names (terminology).

Tedopres International (2009). Articles>Writing>Technical Writing>Controlled Vocabulary