Instructional Design and Software Quality Assurance, Part I  

Describes how instructional design principles can improve documentation.

Nayar, Pawan. Intercom (2001). Articles>Documentation>Instructional Design

Instructional Design: Choosing the Proper Authoring Tool  

Searching for the right tool for your instructional design needs? Learn about your options through capsule reviews of instructional simulation programs and full-service authoring tools.

Holden, Gene. Intercom (2004). Articles>Documentation>Instructional Design

Instructions for Giving Instructions: Creating Effective Documentation  

Increasingly technical communicators are being asked not only to write documentation and instructions, but to also teach subject matter experts how to write their own process explanations. While writing good documentation is an art, there are also formulas and templates that help guide effective process explanation. Whether instructions appear in written, verbal or digital formats, they should all observe basic conventions for graphics, layout, content organization, overviews, development of ideas, ample warnings and cautions, trouble shooting and tool lists.

Stern, Caroline M. STC Proceedings (2005). Articles>Documentation>Writing>Technical Writing

Instructions: Write for Busy, Grouchy People

People hate reading instructions, and will only glance at them when they are hopelessly lost. By then, they will already be frusrated and behind schedule. Organize your instructions carefully, phrase them clearly, and make them as brief as you possibly can.

Jerz, Dennis G. Seton Hill University (2000). Articles>Documentation>Writing

Instructive Interaction: Making Innovative Interfaces Self-Teaching  

An innovative approach to enhancing ease of use and learning for novel user interfaces is described. Instructive interaction comprises a body of techniques based on a learning-by-doing model that is supported by three design principles: explorability, predictability, and guidance. Taken together, these principles form the basis for creative designs that can support highly efficient production use by experienced users while also enabling new users to understand and make effective use of an unfamiliar system almost immediately. The underlying principles of instructive interaction are presented here and an assortment of specific techniques based on these principles is described.

Constantine, Larry L. and Lucy A.D. Lockwood. Constantine and Lockwood (2002). Articles>User Interface>Documentation

Integrating Javadoc (API Reference) with JavaHelp (Online Help): Two Approaches

Although online help (either task-based or UI-centric) and API reference documents serve different purposes, there are times when you may want to at least create associations between the two or at most merge them into one system.

Sapir, Rick. KeyContent.org (2004). Articles>Documentation>Online

Integrating Local and CRI Online Documentation Using SGML and DynaWeb  

This paper tells how Lawrence Livermore National Laboratory enriched CRI's online documentation set by publishing local manuals using the same SGML DTD used by CRI and delivered using (a more sophisticated version of) the same World Wide Web server (DynaWeb 3.0). This approach supports flexible local content and styles, yet integrates local and CRI manuals through one access mechanism and user interface. We explain the basic strategy involved, compare the benefits of this approach with three alternatives, and discuss the problems to which it gives rise.

Girill, T.R. Delft University (1996). Articles>Documentation>Single Sourcing

Integrating Partner Information Using XML and XSL

Having learned that two of these database companies already used single-source files for their error messages, BMC Software integrated the information about the error messages from the database companies. We accomplished our goal by negotiating with our partner companies for the source files of the error message information. This session discusses how we took those source files and modified them to create simple XML files, then transformed them into HTML using XSL transforms within a BMC Software product.

Gentle, Anne. WritersUA (2006). Articles>Documentation>XML>Case Studies

Integrating Training and Documentation  

The potential problems I detailed in working to integrate training and documentation functions do indeed occur in many organizations. They have also found that working out the problems is worth the effort.

Hackos, JoAnn T. ComTech Services (1994). Articles>Documentation>Tutorials

Intentional Learning in an Intentional World: Audience Analysis and Instructional System Design for Successful Learning and Performance    

How do we support successful, lifelong learners and performers and help them competently respond to rapidly changing opportunities in the 21st century. The answer to this question lies in how well we understand audiences differentiated by key learning differences and consider how these differentiations influence winning learning and performance. Historically, cognitive-rich explanations have tended to underplay the dominant impact of affective and conative factors on thinking and learning. Recently, these dimensions have gained considerable importance as contemporary multidisciplinary research has begun to demonstrate how intentions and emotions can influence, guide, and, at times, override our thinking and other cognitive processes. More importantly, research suggests that intentions and emotions are a dominant, powerful influence on learner success.

Martinez, Margaret. Journal of Computer Documentation (2000). Articles>Documentation>Instructional Design>Education

Interactive Electronic Technical Manuals

Advances have been made to provide that information online to the point where electronic access to the information involves nothing more futuristic than a laptop computer and access to a database.

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

Interactive Help: Adapting Content for Multiple Users  

Most online help systems present a 'one-size-fits-all' solution—fixed content for each topic—but users’ experience levels and backgrounds are complex and diverse. Users lose time and patience sifting through topics that either do not match the problem a user is trying to solve, or that present information that does not match a user's knowledge level. A group of Masters students at Carnegie Mellon University tackled this problem. As a course project, the team created an online help prototype that contains different levels of help, a prototype that gives users a choice about how much information they want to see.

Downs, Christina M. and Anne F. Jackson. STC Proceedings (2001). Design>Documentation>Online>Help

International Communication

'Localisation' is the term given to changing the software and the related documentation to suit a particular geographical region. One of the major components of localisation is of course translation. Needless to add, I am talking about localisation from an international perspective. Localisation at the national level would mean having software in Hindi, Marathi, Gujarati, and so on. Surprisingly, this has not happened in a big way.

Kamath, Gurudutt R. IT People (2000). Articles>Documentation>Localization>India

International Considerations in Creating Computer Documentation  

In creating computer software manuals, international users have become an important factor in design decisions. This paper discusses several issues and strategies useful in creating documentation with an international audience in mind.

Smart, Karl L. and Robert Bringhurst. STC Proceedings (1993). Articles>Documentation>Technology>International

International Consumer Protection: Writing Adequate Instructions For Global Audiences    

In 2003, the United States exported nearly $720 billion in goods. Businesses that trade in the global market have a legal and ethical duty to make their products reasonably safe, and technical communicators who write the documentation for those products have a legal and ethical duty to protect international consumers by writing adequate instructions. Writing documentation for products that will be distributed internationally requires not only the ability to communicate clearly, but also awareness of the relevant product liability laws, the cultural variables, and the expectations of international audiences. This article first argues that devoting company resources to produce adequate instructions for international users is both practical and ethical, then provides a brief overview of the consumer protection measures that the top U.S. trade partners have implemented, and finally presents guidelines for developing adequate instructions for international audiences.

Lipus, Teresa. Journal of Technical Writing and Communication (2006). Articles>Documentation>International

Internationalising Documentation

The translation market is growing with tremendous speed. Pressure comes from various angles: volume, time, quality and price. Hence the challenge can be stated thus: Translate more better and in less time at a lower cost! There is no way this can be done without the use of translation tools.

Stücker, Harald. TC-FORUM (1999). Articles>Documentation>Localization

Introducing DocBook

Structured documentation is semantic, rather than presentational. Components have identifiable structure. HTML and Word are somewhat structured. DocBook is strictly structured.

Walsh, Norman. NWalsh.org (2001). Presentations>Documentation>Standards>DocBook

Introduction of Programming Technology for Improving Manual Production  

How do we introduce programming technology successfully and illustrate various applications using SGML, Visual Basic, RTF, HTML and other tools which drastically change the manual production process? The following is an explanation of how we at Seishosha Co., Ltd. have dealt with this matter.

Kobayashi, Norio. STC Proceedings (1995). Design>Documentation>Programming

An Introduction to API Documentation  

This session will help you to: identify relevant source of information; extract information from the source; create effective API documentation; create context-sensitive help for DLLs (Dynamic Link Library).

Dubey, Akash. STC India (2003). Articles>Documentation>SDK>Technical Writing

Review: Introduction to Commentaries on "Spurious Coin: A History of Science, Management, and Technical Writing" by Bernadette Longo    

In past issues of JCD, we have employed graduate students in rhetoric and technical communication to provide their point of view on new books in the field. In this issue's book commentary, I have taken this opportunity one more time as students in a graduate seminar at Michigan Tech - Histories and Theories of Technical Communication - read, discussed, and then responded to Bernadette's Longo's Spurious Coin, A History of Science. Management, and Technical Writing.

Johnson, Bob. Journal of Computer Documentation (2001). Articles>Reviews>Documentation

An Introduction to Embedded Assistance  

Everyone hates help, right? Why? Help is inherently reactive, anticipating users' failure rather than providing information when users need it--before they fail. Print documentation, further from the user’s task at hand, is even more guilty of these sins. This paper presents an overview of embedded assistance, describing the current help paradigm and why it's failing and the basics of embedded assistance, as well as the technologies and infrastructure and the skills and knowledge you need to develop effective embedded assistance.

Ames, Andrea L. STC Proceedings (2002). Design>Documentation>Help>Embedded

Introduction to JavaHelp  

An introduction to using Sun's JavaHelp system for creating online Help.

Nesbitt, Scott. ScottNesbitt.net (2004). Articles>Documentation>Help

Introduction to Writing Software Documentation

Documentation is a vital but often unappreciated part of almost every software product. Most software documentation is written by technical writers, employees who specialize in the field. People not in the field often fail to appreciate just how complex the process of writing documentation really is and how dependent it is on developers and other software professionals. There's also a lot of confusion out there about just what technical writing encompasses.

Karin, Janice. Suite101. Articles>Documentation>Writing>Technical Writing

Is a Documentation Wiki in your Future?

If we can solicit user participation in a Web 2.0 knowledge community (a volunter wiki documentation, for example), we might have a powerful means for creating high quality content. But how should this process work?

Hackos, JoAnn T. Center for Information-Development Management (2007). Articles>Documentation>Content Management>Wikis

Is DITA Going to Tip?

We seem to be heading in the right direction. The danger is that we keep talking to one another rather than evangelizing to a broader community.

Hackos, JoAnn T. Center for Information-Development Management (2005). Articles>Documentation>Standards>DITA