Taking Advantage of Reflexive Responses

None of us likes to admit that we have conditioned reflexes that override our higher cognitive abilities, yet such denials notwithstanding, each of us does occasionally respond without thinking something through clearly. As technical communicators, it's important for us to accept this fact of human nature and plan for it in our documentation, and to work with the developers of the products that we document to both take advantage of the helpful reflexes and find ways to ward off the harmful ones.

Hart, Geoffrey J.S. Geoff-Hart.com (2001). Articles>Documentation>Writing>Technical Writing

Teaching Documentation Writing: What Else Students--and Instructors--Should Know    

Discusses knowledge, problem-solving strategies, and desktop publishing skills students need to learn about documentation writing. Describes a course that provides these skills. Also applies to in-house training programs.

Boiarsky, Carolyn and Michael Dobberstein. Technical Communication Online (2003). Articles>Education>Documentation>Technical Writing

The Team Approach to Writing Policies and Procedures  

Although many companies claim to have working teams within their corporate structure, it may be difficult to use the same approach for writing documentation. With the demands for controlled documentation to meet quality standards, involvement in policy/procedure writing is an important factor in developing a sense of ownership and commitment to maintaining a document control system. A team approach to writing procedures may involve more time, but the results are operations consensus, improved writing skills, and a boost of professional confidence.

Whitmer, Diane L. STC Proceedings (1996). Articles>Documentation>Technical Writing>Collaboration

Technical Documentation Tips

How to write effective technical documentation.

Streight, Steven. Blogger.com (2004). Articles>Documentation>Writing>Technical Writing

Technical Support According to Dilbert

Help desks often follow written scripts based on how an application should work, but what if the user is faced with something out of the ordinary, and it’s something not written in the script? Software might not always behave as it’s supposed to; did a technical writer somewhere have to form a logical conclusion that might not have been correct?

Rosberg, Joe. TechRepublic (2008). Articles>Documentation>Writing>Technical Writing

Technical Writing and Instructional Design Techniques  

Technical communicators and instructional designers use similar techniques in producing written documents. This paper discusses how the Perot Systems Instructional Design team creates its documentation in a similar manner as technical communicators. We start by discussing the use of the ADDIE model for developing documentation; 2) explaining how we implement our Word and PowerPoint style guides with a brief mention about our client-driven Training Engagement Methodology; and 3) ensuring copyrights are respected. The subject matter experts that we support as technical communicators and instructional designers sometimes view us as the documentation police because we constantly question the data and quotations.

Damrau, Jackie. STC Proceedings (2004). Articles>Documentation>Writing>Technical Writing

Technical Writing in Everyday Life: One User's Experience

The experience of setting up a new home theater system also sharply reminded me of what it is like to look at something as a new user: staring at a bunch of knobs and holes for the first time, holding a tassel of wire in one hand and a manual in the other, and really just wanting the darn piece of ?%^%! to do what it's supposed to do.

Vedrody, Sarah. MetroVoice (2002). Articles>Documentation>User Centered Design>Technical Writing

The Technical Writing Process  

The technical writing process consists of four phases: planning, writing, delivery and archiving. The phases of the technical writing process are not necessarily discrete. You might start the writing phase before you complete the planning stage, for example, or you might have to deliver the documentation before you feel it is finished. It is highly unlikely, however, that you will ever archive the documentation before you deliver it! Some products are released several times. In this situation, you might be in the delivery phase of the first iteration of the project while you are in the planning phase of the second iteration. Don't panic: overlap in the technical writing process is quite normal.

Docsymmetry (2003). Articles>Documentation>Workflow>Technical Writing

Technisch Schrijvers Schuwen Onderzoek: Toch Kunnen Onderzoeksresultaten Praktisch Toepasbaar Zijn  

This article, which appeared in the Dutch journal Tekst[blad], describes four recent studies that are relevant to help developers, and suggests how help developers can use the knowledge gained from those studies to improve the performance support systems they build.

Hayhoe, George F. Tekst[blad] (2000). (Dutch) Articles>Documentation>Usability>Technical Writing

Thinking Outside the (Tech Docs) Box: Structured Authoring as Competitive Advantage

There was a time when technical writing was seen as a cost center—a necessary function, but hardly a key lever for competitive advantage. This is quickly changing as globalization and hyper-competition put customers in control and organizations scramble for new and different ways to strengthen relationships.

Sorofman, Jake. Content Wrangler, The (2008). Articles>Documentation>Writing>Technical Writing

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

Types of Documentation Needed by Companies

Every business--large or small--needs documentation to operate effectively. Requirements for extensive internal documentation are spelled out in the ISO 9000 series of international standards. The major classifications of needed documents include marketing, user guides, administrative material and published works. Technical communicators are needed to write each of these types of documents.

Kurtus, Ron. School for Champions (2005). Articles>Documentation>Writing>ISO 9000

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

Using What You Have to Write Help  

Writing online Help carries an unwarranted mystique. Fancy tools, research, and a cooperative development team help a technical writer produce online Help content. What if you have only the software and an assignment? You can use what you have. This approach will help you be a more marketable writer. You will be a more versatile writer, and a better production team member. You can use this easy method to write and organize online Help topics with minimal resources. We hope to take away the mystique.

Anderson, Douglas and Jason R. Huntington. STC Proceedings (1995). Articles>Writing>Documentation>Help

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 a Troubleshooter  

Advises technical writers to create troubleshooters that suggest possible solutions not found in the documentation. She gives examples of troubleshooters for both online and print media.

Darnowsky, Sabrina. Intercom (2001). Articles>Documentation>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