Results of the "Survey of Percentages for Documentation Written on the Topic of Controlled Language (CL)"

Here is a summary of a survey that I conducted in April 1999. These results reflect replies received as of 10 June 1999.

Allen, Jeff. TC-FORUM (1999). Articles>Documentation>Localization>Glossary

Rethinking User-Centered Information Development  

Often in the computer industry there is a tendency to provide information about the features of a system. However, customers usually purchase the system based on knowledge of its features, when they receive the product they need information on how to accomplish tasks. Developing task-oriented information requires a shift in perspective from what the computer technology can do, to what your customers want to do with the technology. The resulting information must be usercentered rather than feature-driven. These types of customer requirements demand afresh development approach.

Stertzbach, Lori A. STC Proceedings (1995). Articles>Documentation>User Centered Design>Usability

The Return on Investment of Documentation and Support

The benefits of user documentation (reduced support calls, increase in the perceived value of the product, happier customers, better customer retention, increase product usage etc) can be identified, but it can be hard to measure them and accurately quantify the Return on Investment.

Pratt, Ellis. Cherryleaf (2008). Articles>Documentation>Management

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

Rhetorical Analysis of a Quick Reference Aid  

The need for timely and relevant computer documentation is a constant challenge. Sometimes there is a need to redesign such documentation to make it more useful. Rhetorical analysis is a useful aid for technical communicators in redesigning such documentation. Using Kenneth Burke’s notion of terministic screens, a quick reference aid for the users of a machine-aided translation system is examined from the perspective of graphic communication. Although rhetorical analysis cannot replace accepted principles of good design, it allows the technical communicator to examine design decisions from another perspective, giving one a very different set of questions to consider and some principles of explanation to justify design decisions.

Brooksbank, Patricia L. STC Proceedings (1993). Articles>Documentation>Methods>Rhetoric

The Right Help in the Right Place  

Originally submitted to Builder.com, this article is an overview of how to add effective help to Web-based applications. It was written for developers and others who are not technical communication professionals. Builder.com changed direction and decided not to publish the piece.

Deaton, Mary M. Builder.com (2003). Articles>Documentation>Help>Online

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

RoboHelp Office v.3x: the Good, the Bad, and the Indifferent

Overall, in my experience, writers and programmers prefer to use RoboHelp to create and maintain Help systems because the application has fewer issues with the Internet and programming platforms. In fact, for this latest version Of RoboHelp, I have only one minor complaint. Here is a summary of my findings.

Hewitt, Sally. MetroVoice (2003). Articles>Documentation>Software>Adobe RoboHelp

RTFM Part II, Looking Beyond the Printed Page

Last month I went through some fairly atrocious documentation. The letters I received from frustrated geeks really drove home the point that bad docs can make what should be a simple, routine, and--dare I say--fun experience, dreadful.

Krasne, Alexandra. PC World (2004). Articles>Documentation>Online>Help

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

Sarbanes-Oxley and Financial Accountability

In the financial documentation realm, there are so many new buzz words, but they all boil down to the documentation equivalent of bean counting.

Albing, Bill. KeyContent.org (2004). Articles>Documentation>Management

Sarbanes-Oxley Compliance: Five Lessons to Reduce Cost and Effort

The Sarbanes-Oxley Act requires every publicly traded company, large or small, to establish internal controls and procedures for reliable financial reporting. Although the Securities and Exchange Commission has extended the deadline for small businesses and foreign entities, these organizations need to begin planning. But as they do so, they can apply valuable lessons learned by large businesses that paved the way to Sarbanes-Oxley compliance (and spent on average of $10 million to do so). Here are the top five lessons learned that will help you reduce the cost and level of effort for achieving compliance.

Nelson, Adam. ComputerWorld (2006). Articles>Documentation>Legislation>Workplace

Screen Captures in Software Documentation    

While screen captures are the most widely used illustrations in manuals, there is almost no literature on their role and design. In this paper we draw together practice, theory and empirical research to advance a taxonomy that identifies these roles and designs. We suggest that screen captures in software documentation can help the user to switch attention, develop a mental model of the program, verify screen states, and identify and locate window elements and objects. Four important design areas (coverage, positioning, size, and cueing) are distinguished and empirical findings discussed. Research has substantiated the claim that screen captures speed up task completion, but others have yet to be proven. We believe that a more refined approach, afforded by the taxonomy, is likely to improve practice and research, and yield strong evidence supporting the use of screen captures in software documentation.

van der Meij, Hans and Mark Gellevij. Technical Communication Online (1998). Articles>Software>Documentation>Screen Captures

Screenshots with the Mouse Pointer

How to produce screenshots which include the mouse-pointer.

Springer, Hans. TC-FORUM (1999). Articles>Graphic Design>Documentation>Screen Captures

Secondary Windows in Online Help - What Do Users Really Make of Them?

Digitext, a UK-based consultancy specializing in online information, has recently conducted two different usability tests, each of which sheds new light on the way in which people respond to secondary windows in online Help. The overall conclusions from the two tests were: there is little reason to assign specific types of topic to different secondary windows; it can be helpful to use a secondary window for a link to a sub-procedure or layer of additional detail, as long as the current window remains visible on screen when the new window appears. This article explains how the tests led to these findings.

Ellison, Matthew. Usability Interface (2001). Articles>Documentation>Help

Section 508, Documentation and the US Software Market

This article outlines how you can ensure that your software documentation conforms to the new accessibility legislation in the US.

Unwalla, Mike. TechScribe (2003). Articles>Documentation>Accessibility>Section 508

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

Sennheiser Wireless Lavalier Microphones

Discusses how to use Sennheiser EW112P(A) Wireless Lavalier Microphones to ensure high-quality audio in video multimedia projects.

Tesdell, Ramsey and Zach Paskiet. Studio for New Media (2004). Articles>Documentation>Multimedia>Audio

Serving Information Workers and Knowledge Workers  

Information and knowledge workers are important users of technical communication products, but they do their work in different ways. Information work (i-work) follows a procedure to achieve a desired and prescribed result. Knowledge work (k-work) is decision making, the process of using one's skills and experiences to solve a problem. Information and knowledge are not always differentiated properly when organizations provide training and documentation for their workers, and information and knowledge tasks are not neatly separated in most business processes. Information and knowledge tasks can be separated and identified, allowing for the development of proper teaching and support materials.

Tillmans, Michael C. STC Proceedings (2005). Articles>Documentation>Audience Analysis

Setting Standards for Documentation Quality  

Managing for quality requires effective, enforced standards. Effective standards make it possible for everyone on the information team to be responsible for quality – for what J.M. Juran has called 'fitness for use.' This paper examines why standards improve quality and what actions are necessary to manage for quality by creating and using effective standards.

Bibus, Connie M. 'C.J.' and Jennifer Bown. STC Proceedings (1995). Articles>Documentation>Standards

Seven (Plus or Minus Two) Things to Remember About Producing Online Documentation  

Producing online documentation requires a new view of a technical communicator's roles, skills, and responsibilities.

Titta, Catherine M. and John E. Johnson. STC Proceedings (1993). Articles>Documentation>Online>Usability

Seven Steps to Successful Online Help  

How do you create an effective online help system and efficiently manage the project? This paper will cover some basics of practical online help design and project management. The presentation includes examples from a project we worked on.

Evans, Jeanette P. STC Proceedings (1995). Articles>Documentation>Online>Help

The Sheer Audacity: Get More, in Less Time

Gives a few pointers on how to give your podcast a more professional sound in addition to a number of easy-to-follow procedures for more complex functions. Though aimed at the beginner and intermediate Audacity user, anyone who wants to save time by using Audacity will find the tips and tricks useful.

Franklin, Jerry. Podcast Academy (2006). Articles>Documentation>Audio>Podcasts

Should Documentation Be Written in English in Countries Where the Natural Language is Not English?

Though ours was quite an international group, we soon found that we shared similar experiences. Comparing our experiences led us to affirm that when non-native writers produce English documents, mother tongue reviewers are required.

Payne-Charby, Anne-Marie. TC-FORUM (1999). Articles>Documentation>Localization

Show Me Demos and Captivate

In this audio-visual age, technical writers need an easy way to deliver Flash-based, dynamic screen demos for their help content.

Johnson, Tom H. and Kevin Siegel. Tech Writer Voices (2007). Articles>Documentation>Multimedia>Flash