To Err in English...

There is such a desperate need for technical writers that anyone and everyone is welcome. My only fond hope is that we deliver quality. The minimum requirements for technical writing are good English-language skills, and proper use of grammar and punctuation. Typically, in most of the user manuals that I have picked up in India, I have always found errors after browsing through a few pages. Some of these errors are gross and some of them are subtle.

Kamath, Gurudutt R. IT People (2002). Articles>Documentation>Technical Writing>India

Too Little, Too Much - A Reviewer's Dilemma  

Even the best planned software projects go through a last minute rush. This late dash imparts risks on the software quality, and on items such as Online Help and User or Technical Guides. Since writing consumes around 80% of the pubs project effort, the remaining time needs to be apportioned for reviewing.

Unni, Tharun Kumar. STC Proceedings (1999). Articles>Documentation>Writing>Technical Writing

User Assistance: Writing for a High-Context Culture

What we consider to be good technical writing often reflects an American cultural perspective. One facet of this cultural orientation is that technical writing tends to use a low-context style. Most notably, we tend to write user assistance as if users have never seen the user interface we are explaining. Secondly, we tend to write user assistance as if users have never even used software before. But users rarely go to Help before they have tried to accomplish a task on their own first, and most users today have extensive experience using software and are familiar with the standard ways of interacting with user interfaces. So a user interface is a high-context artifact—one a user has already seen before reading our documentation and that uses rules and conventions the user already knows.

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

Users' Documentation Preferences

At a user group meeting in 2007, TechScribe researched users' experiences of the software documentation that they receive. Do they prefer online or printed documentation? Do they read the manual, or do they call the help desk? How important is background information? Which is more useful, a 'how to' user guide or a reference manual? Do people prefer explanations using visuals, descriptions, or a combination? Read the survey to find the answers (we obtained 29 responses from 64 attendees).

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

Veteran Neophyte: Confessions of a Veteran Technical Writer

I've been a technical writer long enough to have learned a few trade secrets, if you will, that guide me in my daily work and (sometimes, I hope) help me to do it a little better. Whether you're reading manuals for content, working with technical writers to document your own software, or even writing documentation yourself, understanding these secrets might be of value to you. I've long had it in mind to write a book about these and other topics, sort of a general discourse on technical thought and how to do it better. Until I actually write that book, however, the following confessions will have to do. These confessions should help you understand some of the tasks that some technical writers typically perform and some of the conflicting forces that shape final documents. (Note the profusion of the word some: your mileage may vary.) For fun -- and for another reason that I won't tell you yet -- each confession is introduced by an appropriate palindrome (a word or phrase that reads the same forward and backward).

Monroe, Tim. MacTech (1996). Articles>Documentation>Writing>Technical Writing

What Research About Thinking and Doing Suggests About Technical Documentation  

Users of technical documents need to understand the actions required by tasks and how to carry them out. Users may also want to perform some actions automatically, so that they can devote mental effort to other task components, but requires much practice. Technical documentation can support users effectively when it describes and illustrates in ways that grounded in the physical side of user performance.

Krull, Robert. STC Proceedings (1995). Articles>Documentation>Writing>Technical Writing

What's a Topic?

Back in 1998, I defined topics as "'chunks' of information in a Help file that answer one question or provide focused, specific content." Ten years later, I typically use the same definition. However, there have been some changes in how those "chunks" are developed.

Helpstuff (2008). Articles>Documentation>Writing>Technical Writing

When Tech Writers Don't Read Directions  

Find out what the Unspoken Rule of technical writers is and how to avoid violating it.

Minson, Benjamin. Intercom (2008). Articles>Documentation>Writing>Technical Writing

The Why and How of Content Convergence and Integration

Content producers are about to live through interesting times, to adapt the popular saying, with the dawning of The Age of Content. Industry is discovering content as a commodity; the rules are changing, and fast. What have traditionally been seen as the lowliest form of commercial content within an enterprise, technical manuals, are starting to take their place alongside the other valued corporate assets.

Bailie, Rahel Anne. Writing Assistance (2007). Articles>Content Management>Documentation>Technical Writing

Why Write Instructions That No One is Going to Read?

I know that a lot of people never read instruction manuals or online help. But you know what? Some people do.

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

Writing Application Guides for Technical Products  

Application guides are a type of marketing brochure particularly well-suited to promoting technical products. Through the use of examples they explain how a technology is applied to solve problem of a similar nature. They help organize and simplify complex subjects and, therefore, make a technical product’s benefits more understandable to potential customers. Like other marketing communications, application guides require careful editing and graphical support to make them powerful and persuasive.

Bednarz, Martha C. STC Proceedings (1995). Articles>Documentation>Writing>Technical Writing

Writing Cost-Effective Documentation for Software Systems

There are many situations when you have an application but there is no help file with it, and you have no time to write complete documentation yourself. At the same time you have no budget to hire a professional technical writer who can do this tedious work for you. Let's consider the most common of such situations.

Crane, Dennis. Dr. Explain (2007). Articles>Documentation>Writing>Technical Writing

Writing Help Is...Challenging

I'll never be able to be a technical writer. How do those people do it?

Osherove, Roy. ISerializable (2003). Articles>Documentation>Technical Writing>Help

Writing Procedures Like a Pro: The "How To" of "How To's"   

Do you need to brush up on your procedure-writing skills? Or do you need to teach others--like clients or coworkers--these valuable skills? If procedural writing isn't your focus, keeping these skills honed is a challenge. This workshop is designed for communicators at all levels who must--in some fashion--tell people how to do something. During this highly interactive workshop, you'll find out about the differences between process descriptions and procedural writing, some tips for planning procedures, and the secrets of writing techniques for procedures. So bring your thinking cap, and join a couple of seasoned writers/instructors for this fun and informative session!

Edgerton, Rebecca J. and Jill Nicholson. STC Proceedings (1999). Articles>Documentation>Writing>Technical Writing

Your Role in Supporting Sales-Force Automation  

When given a user manual to write or a Web site to put together, your role as a technical communicator is clear. But what is your role when supporting sales tools? How can you help your company market their technical products? The first step to understanding your role is to understand what a sales-force automation (SFA) solution could mean to your company. This workshop defines SFA and the potential benefits. Further discussion covers deciding on an information delivery method, determining data organization and management, and identifying audience needs.

Caldanaro, Regina M. and Jodie Pait. STC Proceedings (2000). Articles>Documentation>Writing>Technical Writing

The Zen of Minimalism: Designing a Top-of-Class Manual for Beginners and Advanced Users

Can using minimalist documentation improve accuracy and learning speed for beginners as well as for advanced users? I tested this question using Microsoft Access for Windows 95 ® and three different third-party manuals explaining this product. Then I set up three main tasks for the user in a usability test. For each task, I provided the task description in blue type, and then copied the appropriate documentation in black. Documentation for each of the three tasks was reprinted from a different book.

Stieren, Carl. Simware (1998). Articles>Documentation>Technical Writing>Minimalism

A Curmudgeon's Guide to Computer Documentation

Is documentation a bad word? It is if you’re the Curmudgeon, a character I invented, who some say bears an amazing resemblance to … me.

West, Mike. MBWest.com. Articles>Documentation>Technology>Technical Writing

Review: Why Manuals Fail

A very brief review of the first edition of Edmond H. Weiss’s How to Write a Usable User Manual.

West, Mike. MBWest.com (2006). Articles>Reviews>Documentation>Technical Writing

Driving Development

By partly adopting the process suggested by Daniel Brolund we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.

McLean, Gordon. One Man Writes (2008). Articles>Documentation>Writing>Technical Writing

Collaborative Walkthrough Video

Collaborative walkthroughs are a technique that my team used while rewriting our Help and adopting DITA. We believe that we were able to improve the user experience by improving the collaborative experience.

Bennett, Miranda. On Writing (2008). Articles>Documentation>Collaboration>Technical Writing

Writing with Authority

Technical writers write with authority. That’s the job: to present the subject with authority, so the reader will feel confident about the accuracy of the information or confident about using the software. There’s no place for hedging. You write, ‘Press the OK button’. You don’t write, ‘Press the OK button – I think.'

Bristow, Gemma. Inkjuice (2008). Articles>Writing>Technical Writing>Documentation

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>Help

Building a DITA-Wiki Hybrid  

Learn about theoretical and practical examples of merging DITA (Darwin Information Typing Architecture), a structured authoring methodology, and wiki’s freeform authoring and editing capabilities.

Gentle, Anne and Lisa Dyer. Intercom (2008). Articles>Documentation>Technical Writing>Wikis

The "Quick Web" for Technical Documentation  

So how did the wiki become a seemingly permanent fixture in the landscape of today’s Web? Which wikis have succeeded as technical documentation, and how can we replicate their success?

Gentle, Anne. Intercom (2007). Articles>Documentation>Technical Writing>Wikis

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.

Great Technical Writing (2008). Articles>Documentation>Usability>Technical Writing