Information Metrics: Keeping Your Writing Projects On Track  

Keeping information metrics for documentation projects gives managers the ability to more accurately estimate future projects. Publications departments can develop their own tools or they can use existing tools to track such things as page size, hours-per-page spent writing, illustrating, editing, and producing manuals; and the dependencies of each manual. This kind of information can help to determine development schedules, show how late changes affect the documentation process, and accurately determine what it will take to complete quality documentation on time and within budget.

Gordon, Judy L. STC Proceedings (1993). Articles>Documentation>Project Management>Methods

Information Planning for Successful Online Documentation  

Creating an information plan should be the first phase of any publication development life cycle, whether hard copy or online. The plan is a tool for reporting the results of your research about your audience, their tasks, the market, and the product. The plan presents the basic organization and content of the publications you intend to build, effectively directing the documentation team to produce a publication with very specific goals in mind.

Stevens, Dawn M. STC Proceedings (1996). Articles>Information Design>Management>Documentation

An Introduction to DITA

Writing, compiling, and maintaining documentation is a necessary evil. While moving to DITA might not improve the quality of your documentation, it can streamline the process of creating and managing those documents.

Nesbitt, Scott. InformIT (2006). Articles>Documentation>XML>DITA

Insert Clever Title Here: Creating and Using Multi-Purpose Information Blocks for Documentation and Training  

Our technical writers and course developers share several objectives. We must provide task oriented information to our customers, we create information for a variety of products, and we follow a similar information development cycle. We also spend a great deal of time re-creating the same information over and over. To make our efforts more efficient, and to creole better information for our customers, we’ve changed the way we think of information, how we initially create the information, and how we store and retrieve the information. This paper describes the methods we chose to accomplish these goals, the tools we use, and our successes, failures and frustrations.

Brockett, Susan H., James Cox, Lelanie S. Hellmer and Susan Katz. STC Proceedings (1995). Articles>Documentation>Education

Inspecting Requirements

Errors in requirements specifications translate into poor designs, code that does the wrong thing, and unhappy customers. Requirements documentation should be inspected early and often. Anything you can do to prevent requirements errors from propagating downstream will save you time and money. Karl Wiegers shows you how.

Wiegers, Karl E. StickyMinds (2004). Articles>Documentation>Engineering>Specifications

Instruction-Writing Exercises (for High School)

These guidelines and 14 scaffolded exercises respond to the unmet need for a psychologically solid, work-relevant way to learn technical writing by students who are NOT facile writers already.

Girill, T.R. STC East Bay (2001). Articles>Education>Instructional Design>Documentation

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

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

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

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