Implications for Writers Documenting Object-Oriented Projects  

Object-oriented (OO) projects bring with them new technology and new processes. While programmers focus on the OO methodologies governing design and implementation of program code, writers must struggle to adapt to a very different kind of development cycle. To avoid chaos, development teams must explicitly define their processes from the start.

Berry, Robert R., Karen L. Mobley and Kathryn L. Turk. STC Proceedings (1994). Articles>Documentation>Software

Implicature, Pragmatics, and Documentation: A Comparative Study    

This study investigates the link between the linguistic principles of implicature and pragmatics and software documentation. When implicatures are created in conversation or text, the listener or reader is required to fill in missing information not overtly stated. This information is usually filled in on the basis of previous knowledge or context. Pragmatics, the study of language use in context, is concerned with the situational aspects of language use that, among other things, directly affect implicatures required of the reader. I investigate how two manuals for the same software product can be analyzed on the basis of implicature and pragmatics. One is an original copy of the documentation that came with the product, the other an after-market manual. Results show that the aftermarket manual requires far fewer implicatures of the reader and does a better job of providing pragmatically helpful information for the user.

Wright, David. Journal of Technical Writing and Communication (2007). Articles>Documentation>Rhetoric>Technical Writing

The Importance of Software Documentation Standards

The look and feel of a help system can differ greatly from one product to the next, as can the writing. So how can the technical writing community emphasize the importance of software documentation standards and create a more unified help experience that users can adapt to?

Helpscribe (2008). Articles>Documentation>Standards>Software

Improving Document Quality Through Customer Visits  

In an effort to improve the quality of our documentation, our Information Development department personally visited over 80 of our customers in 10 different locations across the United States. Our goal was to find out what we needed to do to create documentation that would satisfy our customers' needs. We came up with a process for planning our visits, gathering the information from our customers, implementing their requirements, and increasing communication with them. From the visits, we not only made changes that immediately satisfied our customers, but we created an environment for them to work with us as a team.

Lass, Laura W. and Wendy L. Reed. STC Proceedings (1993). Articles>Documentation>Quality>User Centered Design

Improving Documentation Through Customer Feedback: A Case Study  

By soliciting and receiving customer feedback, writers learn how customers use existing documentation and what additional information customers may need. In May 2001, we began a formal process of gathering customer feedback for the IBM WebSphere Commerce Suite product. The first phase of this process involved two main initiatives: creating and promoting a documentation questionnaire for customers; creating and working with an internal test team that acted as customers. Feedback allowed us to determine which information strategies helped customers meet their business needs, and which areas we need to concentrate on in future releases.

Heximer, Erin and Lisa Wu. STC Proceedings (2002). Articles>Documentation>User Centered Design

Improving Documentation with Learning Techniques  

It is important to recognize that because we all differ in our experience and background the learning process is different for each of us. Consequently, in our documentation we should by to put users on an equal footing by, for example, clearly and exactly defining terms we use and including a glossary. We can also put everyone on an equal footing by using 'bridges to understanding,' from analogies, examples, and metaphors to mnemonic strategies. For overall comprehension, we can employ 'frameworks,' from conceptual maps to road maps, that give patterns of meaning to what we say.

Livingston, Dick. STC Proceedings (1993). Articles>Documentation>Instructional Design>Glossary

Improving Medical Treatment Procedures  

Technical writers should be alert for opportunities to improve documentation in one technical field by using appropriate techniques from other fields. In this paper, the author presents ways of improving medical treatment procedures by using elements from engineering procedures, including introductions, safety sections, warnings, conditional (branching) statements, and notes.

Gibbs, Judith M. STC Proceedings (1996). Articles>Documentation>Biomedical>Policies and Procedures

Improving Publication Quality Through Project Management  

A methodology for developing high-quality software developed by the Software Engineering Institute at Carnegie-Mellon University can also be applied to developing technical publications. This workshop addresses several aspects of this methodology using various project management techniques. By bringing your development process under better control, these techniques will ensure a more uniform quality in your publications.

Firman, Anthony H. STC Proceedings (1995). Articles>Project Management>Documentation

Improving the Quality of User Manuals in Japan  

We will share the results and analysis of a survey on customer needs for user documents as a means to raise the overall quality of such materials. Fuji Xerox will provide how to improve the quality of user documents with some examples of user manuals for copier and facsimile etc. Hitachi will report various methods to improve the quality in software-manual development process and provide some examples.

Nomizo, Fumitoshi, Teruaki Shioda and Akihiko Suzuki. STC Proceedings (1994). Articles>Documentation>Regional>Japan

Improving the Usability of Programming Publications  

This paper summarizes the work of a study group on ways to improve the usability of publications that support programming products. Task orientation, an approach to providing, organizing, and packaging information, is covered, together with innovations to improve the usability of programming publications: ease-of-use education, measurement of user opinion, and incorporating usability into the publications development process.

Bethke, W.M., P.H. Dean, E. Ort Kaiser and F.H. Pessin. IBM Systems Journal (1981). Articles>Documentation>Writing>Technical Writing

Improving Your Technical Document Writing Skills

Discusses the general technical writing process.

Doddihal, Vinayak. EditSphere (2008). Articles>Documentation>Writing>Technical Writing

In Defense of Print

The reduced reading speed on computers can be compensated by good hypertext design that allows the user to read less information and to find it faster. A typical example is online help and documentation: because the information is right there on the computer, there is no need to spend time finding the hardcopy manual, and because of good search tools and hypertext links between related information, users can go directly to the one or two sections that contain the answer to their problem. After all, Nielsen's first law of computer documentation is that users don't read it. The second law is that if they read it anyway, it's because they are in deep trouble and need the answer to a specific problem. Thus, somebody reading a manual won't really read it cover-to-cover, so online presentation makes perfect sense.

Nielsen, Jakob. Alertbox (1996). Articles>Documentation>Online>Usability

Including Purpose in Software Documentation  

Argues that technical writers should include a discussion of the purpose behind every procedure described in software documentation.

Block, Barbara M. Intercom (2001). Articles>Documentation>Writing

Incorporating Animation into Help Files  

Information clarity, ease of use, and modern computing speeds are reasons to consider animation in Help files. Sharp's article presents three common types of animation and how to make them work for you.

Sharp, Roger A. Intercom (2007). Articles>Documentation>Video>Flash

Incorporating Usability Testing into the Documentation Process    

Describes how one company approaches usability testing of documentation and incorporates usability testing into its writing process through a Documentation Usability Team.

Postava-Davignon, Christi-Anne, Candice Kamachi, Cory Clarke, Gregory Kushmerek, Mary Beth Rettger, Pete Monchamp and Rich Ellis. Technical Communication Online (2004). Articles>Usability>Methods>Documentation

Increasing User Acceptance Of Technical Information in Cross-Cultural Communication    

A significant problem in technical communication is persuading the user that the information is accurate, valid, and useful. All too often, technical communicators treat users as members of their own culture. When authors do consider cultural issues, they often focus on matters such as vocabulary, visuals, and organization. Other strategies, however, can be useful in gaining acceptance of technical information in cross-cultural situations. For example, the communication theory of compliance-gaining offers suggestions for how the technical communicators can adapt the text to enhance user acceptance when communicating to members of their own culture as well as when communicating across cultures. Communicators can use promises, threats, demonstrate positive and negative outcomes, extend friendliness, etc., to develop the text. In this article, I will explain several compliance-gaining strategies authors can use, identify rhetorical strategies they can combine with compliance-gaining strategies, show how these strategies can be effective in a cross-cultural environment by comparing the strategies in two sample cultures, and analyze a brief sample.

Warren, Thomas L. Journal of Technical Writing and Communication (2004). Articles>Documentation>User Centered Design>International

Indexing a Software Manual  

Indexing a software manual is not very different from indexing any other manual. As a simple rule, make sure you index all of the software features: screens, windows, fields, options and commands. Index system errors and warnings if applicable. Use cross-references to direct the reader to the term used in the manual if it differs from the generally-used jargon.

Tetreault, Edouard. STC Proceedings (1993). Articles>Documentation>Indexing

Indexing in the Documentation Process: Which Methods Do You Choose?  

Giving your readers a quality index takes a careful consideration of the tools, time frame, workgroup process, and results you plan for the piece. Planning for the index must start at the beginning of the project, in order to have the essential processes clear to all involved As the documentation process itself becomes more complex, trying to meet different needs in different environments, so does indexing. As print-based documentation moves to online, the index or keywords becomes critical to your users. In this session, participants will learn what kinds of tools are available for indexing, the benefits of each, what the stages of indexing are, and the amount of time to allow for each.

Wright, Jan C. STC Proceedings (1996). Articles>Documentation>Indexing

Indexing Online Help  

In order to make a help system really helpful, you need to provide an effective index. But many online help writers face two dilemmas when it's time to index their help systems: How to prepare a useful index that meets the users' needs and how to code the keywords to make the index compile correctly. This article provides tips to help writers solve both problems.

Hamilton, Beth. STC Indexing SIG (1999). Articles>Documentation>Online>Help

Indexing Technical Documents  

Creating an index for a technical manual requires an understanding of what constitutes a high-quality index and the indexing methodology. This workshop presents the methodologies and steps necessary to create such an index.

Bonura, Larry S. STC Proceedings (1993). Articles>Documentation>Indexing

Indicating Changed Text in Help Files

There are still many circumstances when drawing a user's attention to changed text is important. How do we do that with Help systems? By borrowing techniques from paper manuals, we don't have to reinvent the wheel. So here's a good approach that will work for Microsoft Word-based HATs.

Self, Tony. HyperWrite (2004). Articles>Documentation>Online>Help

Information Engineering: Taking Technical Communication to the Next Level  

The technical communication community can no longer be satisfied to produce documentation that scores high in quality but low in effectiveness. We must use whatever means necessary to ensure our users reach their goals with as few obstacles and distractions as possible. This will require us to change the very nature of our work, from simply documenting complexity to designing collaborative systems. Our ultimate goal is not to write a better manual or online help system or web page, but to ensure that human beings and products can work together effectively to achieve common objectives.

Bowie, John S. STC Region 7 Proceedings (2003). Articles>Documentation>Usability

Information Gathering for Policies and Procedures  

Information gathering can be one of the most timeconsuming and potentially frustrating experiences when writing policies and procedures. Policy and procedure writers sometimes start from scratch and must investigate and research policies and procedures before the first word is ever written. Although there are many obstacles to obtaining accurate and timely information, there are also many avenues the policy and procedure writer can take to gather, utilize, and maintain information.

Dodwell, Christine. STC Proceedings (1996). Articles>Interviewing>Documentation>Policies and Procedures