Has Anyone Used Your Product

Before you release a product, have some people use it. From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users. Put that information in your User Documentation, and on your product support website.

Great Technical Writing (2008). Articles>Documentation>Technical Writing>User Centered Design

'Read Rage' Over Instruction Books

"Read rage" is sweeping the UK - as consumers become fed up with the often incomprehensible language used in many of the instruction manuals produced by manufacturers.

Channel 4 (2008). Articles>Documentation>Technical Writing>United Kingdom

Glossaries Aid Clarity

A glossary is an alphabetically arranged list of terms, with a definition or an explanation of each term. A term can be a single word or many words. Typically, in a printed document, the glossary is at the end of the document. Usually, in online help, each term in a topic, or the first instance of a term, has a popup that explains the term.

Unwalla, Mike. TechScribe (2007). Articles>Documentation>Technical Writing>Glossary

Writing for an International Audience

Ideally, software and its documentation is localised (translated) into the languages of the target markets. However, in many cases, it is not cost-effective do this. Even if the target markets are the English-speaking countries, differences exist between the way English is used in the US, the UK, and Australia for example, and it is easy to cause confusion. This article examines some issues.

TechScribe (2007). Articles>Documentation>Technical Writing>Localization

How to Write Good FAQs

FAQs don’t have that great a reputation, but recently, I’ve been working on FAQs for a client. Their computer help desk was annoyed about answering the same things again and again. Why not divert potential callers to a FAQ instead?

Jarrett, Caroline. Usability News (2007). Articles>Documentation>Technical Writing>FAQ

Help for Help files

Normally I like to write positive stuff and I really love Uxmatters.. it’s a great site. BUT, the recent article PDF Manuals: The Wrong Paradigm for an Online Experience from my perspective is pretty much everything that’s wrong with Help today.

Lang, Keith. UI and Us (2008). Articles>Documentation>Writing>Technical Writing

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

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

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

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

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

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

Emotional States of Computer Users in Times of Frustration

If there’s one undeniable characteristic of the frustrated computer user, it’s that her patience is gone. She will not be slowly flipping through the user manual. Notice her jerky movements. If she turns to the help (which she doesn’t here), she’ll search for keywords, skim rapidly, click quickly from topic to topic. As we write for users in this state of mind, we have to remember the hurry.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Emotions

Ten Commandments of Storytelling as Applied to Technical Documentation?

Anyone who reads this blog will know that I’m a strong advocate of storytelling in all forms of communications. I believe that it applies as much to technical or marketing communication as it does to your favorite novel or movie. This article applies McKee’s 10 Commandments to Technical Documentation.

Porter, Alan J. Content Pool, The (2009). Articles>Documentation>Technical Writing

How to Comply With Moral and Ethical Standards in Technical Documentation

Technical writing has a number of moral and ethical standards that a professional technical writer needs to comply with. Violate them at your own peril, by risking the sudden demise of your career. Here are some of these issues.

Akinci, Ugur. Technical Communication Center (2009). Articles>Documentation>Technical Writing>Ethics

Wurman’s LATCH Model of Information Organization For Technical Documentation

Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant.

Akinci, Ugur. Technical Communication Center (2009). Articles>Information Design>Documentation>Technical Writing

Advantages of Using Microsoft SourceSafe While Writing Your Technical Documents

Microsoft’s Visual SourceSafe was not created with technical communicators in mind. It was created for engineers writing software source code. But it is successfully used by technical writers in offices around the world to control documentation.

Technical Communication Center (2009). Articles>Content Management>Documentation>Technical Writing

How to Use the Bulleted Lists Properly in Your Technical Document?

Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists.

Akinci, Ugur. Technical Communication Center (2009). Articles>Documentation>Style Guides>Technical Writing

Structured Authoring for Everyone

While the concepts of structured authoring are more than just slightly useful for technical writing, they can be beneficial for just about any writing task within an organization. But how do you bring XML-based structured authoring to the masses? Perhaps by taking a cue from a word processor called Yeah Write.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>XML>Technical Writing

Where Did All the Documentation Go?

Documentation is a huge cost factor in software development, and companies are looking for ways to trim costs. If you cut back on product doc and customers don't complain, there's a temptation to keep cutting. Eventually you end up with software engineers writing bits of doc because all the tech writers were laid off, but there'll be one guy who didn't get laid off who has to work like heck to wire it all up and make it continue to look like professionally written doc.

assertTrue (2009). Articles>Documentation>Programming>Technical Writing

Quick Reference Guides: Short and Sweet Documentation

In this article, my colleague and I provide strategies, tips, and approaches we’ve learned in creating quick reference guides for software documentation projects.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Quick Reference

What Should You Include in Your User Documentation?

Technical authors are faced with limited time and resources, so they often are faced with the dilemma as to what to include and what to leave out of their user documentation. You may ask, if 80% read only 20% of the content, is there any value in documenting the rest?

Cherryleaf (2009). Articles>Documentation>Technical Writing

The Matter of Dark Text

Dark text refers to the many layers of hidden meaning in any text segment. It ranges from the implied meaning that the author intended, or that the reader infers, to much deeper, more hidden meanings. As technical writers, we must be aware of dark text, and where possible, try to minimize it.

Tech Writer's World, A (2009). Articles>Documentation>Technical Writing