The Keys to Clarity, Consistency, and Correctness

How can you make documentation more clear, consistent, and correct for your users? Following are some guidelines I find effective when documenting concepts and organizing documents.

Hassell-Corbiell, Rives. Indus (2002). Articles>Documentation>Writing>Technical Writing

Let the User Write the Documentation  

Teaching non-writers how to write can be challenging, especially when they are adults using new software to do their jobs. But who knows best how to write about their jobs than the end users. Through field experiences and case studies, this paper describes methods and approaches for eflectively including the end user in the documentation process, as well as educating experienced writers who are new to the system.

Doyle, Diane J. and Janet M. Samuelson. STC Proceedings (1997). Articles>Documentation>Education>Writing

Life: A User's Manual

With his back towards the reader, a bucket over his head, hands and feet tied up by SGML, CALS and company standards, and half choked by all the possibilities of the latest computer system the writer tries to produce manuals and instruction books for unsuspecting readers!

Forsslund, Lars. TC-FORUM (1998). Articles>Documentation>Writing>Technical Writing

Making Documentation Accessible to Users With Disabilities  

Good documentation takes into account the needs of people with disabilities. Such documentation is termed 'accessible' and provides support for the assistive technologies used by people with disabilities. For example, accessible documentation provides a text equivalent for each graphic element, such as a picture, flow diagram, or icon. This provision is necessary for users who rely on screen readers to read the documentation.

Chappell, Gail B. STC Proceedings (2003). Articles>Documentation>Accessibility>Technical Writing

Making Product Information an Integral Part of the Development Process  

Document inspections formalize the document review process and encourage the full participation of technical developers in the documentation development process. A document inspection consists of three parts: a briefing meeting, a desk review, and a recording meeting. At the briefing meeting, you state your requirements for the inspection process. During the desk review, the technical developers review your document. At the recording meeting, you review the comments made by the technical developers, and as a group decide on appropriate resolutions.

Hildebrand-Lund, Ruth. STC Proceedings (1996). Articles>Documentation>Workflow>Technical Writing

Making Sense of Step-by-Step Procedures    

Procedural instructions that consist of only a sequence of steps will probably be executable, but nevertheless 'meaningless' to users of technical devices. This paper discusses three features that can make procedural instructions more meaningful: adding functional coordinating information, adding information about the use of the technical device in real life, and adding operational information about how the device works. The research literature supports the effectiveness of the first feature, but offers little evidence that real life elements enhance understanding of instructions. As for operational information, the research suggests that users are willing to read it, and that it contributes to better understanding and performance in the long term, but only if it is closely related to the procedure. As a conclusion, we propose a theoretical framework that assumes three levels of mental representation of instructions: syntactical, semantic, and situational.

Steehouder, Michael F., Joyce Karreman and Nicole Ummelen. ACM SIGDOC (2000). Articles>Documentation>Rhetoric>Technical Writing

Managing the TWI Mailing List: As Tough as it Gets

The success or failure of any mailing list depends entirely on its members - as in how effectively can they contribute on the list or how diligently can they enhance the quality of ongoing discussions. If you watch closely, the level of discussions combined with the maturity of posters is what characterizes these mailing lists to a large extent. For instance, take a firsthand look at Technical Writers India mailing list or TWI, as it is popularly called.

Prabhakar, Rahul. Blogspot (2006). Articles>Documentation>Technical Writing

Meaningful Microcontent

Microcontent refers to small, granular, and possibly representative (that can provide a summary of or a navigation to a larger set of information) bits of information, typically available on the Web. An example in the domain of journalism might be headlines and news summaries, small bits of content that can be used on a front page of the news with links to more in-depth articles. The definition has grown in scope as much as in its application.

Albing, Bill. KeyContent.org (2006). Articles>Documentation>Content Management>Technical Writing

Method of Text Presentation

A problem that sometimes occurs, when authors ask my advice about the method of presenting an instruction, is that they use words that I think will not necessarily be understood by people whose mother-tongue is not English.

Farrington, Gordon. TC-FORUM (1999). Articles>Documentation>Writing>Technical Writing

Mistakes Technical Writers Make  

Inexperienced technical writers typically make a number of avoidable mistakes, including parroting the SME and hard-coding xrefs. Here is a description of some mistakes to avoid.

Docsymmetry (2003). Articles>Documentation>Technical Writing

Musings on User-Generated Documentation

User-generated documentation is a big issue in technical communication circles. If properly done, tapping into the knowledge of users can improve the quality and breadth of your documentation.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

Nine Tips for Writing Better FAQs

Frequently asked questions, or FAQs, are an important part of your product documentation. Writing well-targeted and thorough FAQs allow users to quickly find the answers they need so they can be more productive when using your product. Here are some tips for writing FAQs that will get your users on track quickly and help reduce Customer Support calls.

HelpScribe (2008). Articles>Documentation>Writing>FAQ

The Presentation of Safety Information in Product Manuals  

Technical communicators may be asked to design and develop safety information for a product manual. During this process, technical communicators can add value to the presentation of safety information. In addition to adhering to a manufacturer’s internal guideline for the content and formatting of safety information, other factors can be considered as well. This paper presents the following factors: (1) an overview of common failure-to-warn allegations, (2) an analysis of current practices in automotive owner’s manuals for presenting safety information, and (3) an update on a new ANSI Z535 consensus standard for the presentation of safety information in product manuals.

Wisniewski, Elaine. STC Proceedings (2005). Articles>Documentation>Risk Communication>Technical Writing

The Procedure Writer©: A Wizard, A Writing Guide And Nine Magic Templates  

The Procedure Writer is an easily navigable collection of steps: a wizard with seven windows, nine templates, and instructions that offer the user-cum-writer the maximum freedom in determining how a module is written. At the same time, the instructions and the nature of the templates are designed to obligate the writer/user to follow P&P standards.

King, Geoffrey, Tom Tomasovic and Mandy Huang. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing

Putting Service and Support Documentation Online—Avoiding the Perils and Pitfalls  

Customer satisfaction studies are valuable tools for developing documentation strategies. Information developers at Compaq Computer Corporation used a satisfaction study to develop a comprehensive strategy for producing online service and support documentation.

Siemers, Linda K., Michael R. Cloud and JoAnn T. Hackos. STC Proceedings (1995). Articles>Documentation>Writing>Usability

Reducing Complexity in Documentation  

With more emphasis being placed on customer satisfaction, technical writers need to focus on information strategies that will lead to happier customers. The complexity of the information is one common complaint of customers. Writers need to understand what customers think is complex. Then, writers need to develop strategies to combat these complexities.

Roscoe-Iverson, Ellen. STC Proceedings (1993). Articles>Documentation>Technical Writing>Minimalism

The Rhetoric of Critical Procedures

One important aspect of technical writing is the production and use of procedures. Though technical writing serves a variety of purposes, teaching, informing, persuading, and even questioning, one of its primary and most common purposes is the 'how-to' function of providing procedures. There is a great deal of information available on writing procedures, the vast majority of it focusing on software documentation and product documentation.

Boelter, Walter H. Orange Journal, The (2003). Articles>Documentation>Rhetoric>Technical Writing

Robert Pirsig’s Message for Documentation Quality  

Teachers of technical communication frequently recommend that their students read Robert Pirsig's Zen and the Art of Motorcycle Maintenance (1974) for his views on the complex relationships between technology and human values. As a former technical writer, Pirsig also offers some useful advice about Quality and its relation to the usability of technical documentation. Revisiting Pirsig’s works, including the more recently published Lila (1991), reveals concepts about Quality in documentation that are especially relevant to the usability testing of the documentation for today’s rapidly evolving technologies. This paper examines Pirsig’s views on the some of the characteristics of effective technical communication, and it offers advice to educators and trainers for incorporating Pirsig’s concepts about Quality into their teaching of techniques for the usability testing, and hence quality, of user documentation.

Shirk, Henrietta Nickels and Howard T. Smith. STC Proceedings (1998). Articles>Documentation>Quality>Technical Writing

S1000D: A Standard for Technical Documentation  

S1000D is a military standard for the creation and delivery of technical documentation. Many companies can benefit from its methodology. Review its history and principal concepts, and learn important information to keep in mind when applying the standard to your work.

Weidenbrueck, Dieter. Intercom (2006). Articles>Documentation>Standards>Technical Writing

Security Policy and Procedures Documentation

With the nation intensifying its homeland security and industry focusing on computer security, the experienced technical communicator can assist with documenting procedures.

Albing, Bill. KeyContent.org (2004). Articles>Documentation>Policies and Procedures>Technical Writing

Software Development Kit (SDK) Documents in 10 Simple Steps

Here are the ten simple steps to successful software development kit (SDK) documentation.

Buck, Catherine. KeyContent.org (2004). Articles>Documentation>SDK>Technical Writing

Software Documentation

Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it. In fact, the term software documentation means different things to different people. This article describes the term as used by the largest groups of users.

Wikipedia. Articles>Documentation>Writing>Technical Writing

Software Documentation Process: Symbios Logic  

This panel presents the software documentation processes of three companies. Participating on an interface design team allows writers to contribute to a software’s usability and to develop supporting documentation early in the software’s development cycle. This presentation summarizes the crossfunctional team’s process and strategies for designing the interface and for preparing usable support products. I will also review the successes and problems we encountered as we created online help and a printed user guide. Writers can learn about Symbios Logic’s interface design team as one approach to creating usable software with accurate, quality documentation. At Symbios Logic, one of our goals is to develop data storage products supported by accurate, easy-to-use documentation. The major challenge we face in completing this documentation is meeting the release dates for our products. To achieve this goal, we are re-designing our latest software by combining both interface and documentation development into one design process.

Burroughs, Dia H. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing

Starting with the Vendor's Documentation  

When a company purchases software for in-house implementation technical writers can contribute to the implementation and training by customizing the vendor’s documentation. This paper describes three strategies with case histories: rewrite; revise and expand; supplement. It offers hours-per-page statistics for comparison and outlines a method of analyzing how much to invest in additional documentation. This paper focuses on user’s guides, but the logic also applies to training guides and on-line help.

Littlewood, Ann P. STC Proceedings (1995). Articles>Documentation>Writing>Technical Writing

Strategies for Winning Recognition: Building a Visible, Viable, and Valuable Documentation Team  

Technical writing teams can improve their standing within their organizations. The purpose of this presentation is to share our experiences at Mirant where we've achieved recognition and respect as a vital internal service to the IT department and, increasingly, to the rest of the company.

Harkness, Holly E. STC Proceedings (2003). Articles>Documentation>Collaboration>Technical Writing