Designing Effective Single Source Materials  

People often have to create documents for different audiences and for different media, (e.g. web, Help, training). However, timelines and budgets for developing information are often tight. This means we have to find more efficient ways to develop information. One way is to consider single sourcing information for multiple users and media. While single sourcing does take more up-front planning, it can significantly decrease costs and development times once implemented.

Rockley, Ann. STC Proceedings (2000). Presentations>Documentation>Single Sourcing

Designing Effective User/Training Documentation with the Learning Style Inventory (LSI), the User Empowerment Inventory (UEI), and Think-Aloud Protocols  

While there are many instruments that measure the capacity for establishing peer-level communication skills, few exist that evaluate the effectiveness of knowledge transfer in the writer-reader relationship. The Learning Style Inventory (LSI), the User Empowerment Inventory (UEI), and thinkaloud protocols help assess how people acquire new knowledge and process information. The results of such measurements/ observations help determine user requirements. This paper presents a case history of how the LSI, the UEI, and think-aloud protocols helped improve both user and training documentation to a technology-averse audience in a reactive project environment.

LeVie, Donald S., Jr. STC Proceedings (1996). Design>Documentation>Methods>Usability

Designing Embedded Help to Encourage Inadvertent Learning    

What do we do when a legacy help system has trained the users not to use it? How do we design a solution that not only lures users back to the user assistance, but also encourages users to learn more about the product? This article follows the decision-making process of a design team that had to solve these problems. Additionally, the design team had to craft solutions for an application that imposed extreme limitations on those solutions, both in help system implementation and information design.

Mobley, Karen L., Clinton Knight and Timothy Meserth. Technical Communication Online (2003). Design>Documentation>Help

Designing for Interactivity: Role Models, Guides, and Coaches  

This paper presents three methods of user assistance: role models (simple demonstrations), guides (structured walk-throughs), and coaches (active assistants). After a brief introduction, potential uses, available development tools, and additional information sources are discussed for each method.

DeLoach, Scott. STC Proceedings (1998). Articles>Documentation>Help>Interaction Design

Designing for the Web: Special Considerations for Safety Information  

Manufacturers are currently grappling with determining whether they should put safety information on the Web and if they do how it should be presented. Technical communicators, Web content developers, and Web designers will ultimately be responsible for the presentation of Web-based safety information. This article discusses special considerations that should be given the formatting (HTML, PDF, etc.), design, (font, size, and color), and location of safety information on the Web. Additionally, areas for future research on the issue of Web-based safety information are identified.

Tallman, Lisa A. STC Proceedings (2001). Presentations>Web Design>Documentation

Designing Help Text

In an ideal world help text would be unnecessary - users would never get stuck in an application or site. It should be enough to provide clear design, carefully chosen titles and labels for the various functions, appropriate field prompts when user entry is required, helpful feedback, a glossary, and 'embedded' help such as default values, example input, on-screen step-by-step instructions and explanatory text next to fields or functions. Help features should certainly be a last resort. Anyone embarking on adding it to an application or site should be sure that they have already followed the best practise listed above. In most cases (certainly online) a help option should not be necessary.

Farrell, Tom. Frontend Infocentre (2001). Design>Documentation>Help>Online

Designing Information for the Online Medium  

Well-designed online documentation exploits the medium to make the content more accessible and effective. Knowing who needs the information and understanding when and how much of it will be used are essential for the creation of effective online content. Ideally, online documentation should answer each question with just the right amount of depth and detail. Considering user expertise, information needs, and usage patterns before creating the content or structure results in information that can be scanned, searched, surfed, referred to, read, or printed equally effectively—exactly what people expect from online documentation.

Mehrotra, Rahul and Jane Nye. STC Proceedings (1998). Articles>Documentation>Online

Designing Installation Manuals Used in Various User Environments  

Manuals normally contain information regarding all the functions of a given product. Therefore, there are cases when information required by one user is useless to other users. As a typical example, for users, performing a version upgrade, the upgrading procedure is important, but the procedure for new installation is useless information.

Shimosaka, Yuji. STC Proceedings (1999). Articles>Documentation

Designing Multi-Platform Online Help: A Demonstration  

Designing multi-platform online help can be made more efficient by placing special effort in the design of the development plan. If the development plan is broken up into four key elements the resulting multi-platform design will yield a great amount of latitude for both maintenance and future enhancements. During the demonstration we will discuss our use of these elements to design both online and hardcopy documentation to support both a mainframe and a windows interface.

Taylor, Shhonn D. and Pat Straw. STC Proceedings (1996). Presentations>Documentation>Help

Designing Object-Oriented Documentation  

Describes how to construct documentation using the object-oriented model.

Beg, Visja. Intercom (2000). Design>Documentation

Designing Online Help for Pocket PCs

Advances in technology in the last ten years have created an emerging category of portable online computers (Pocket PCs or PPCs) that offer a wide range of product features comparable to Personal Computers (PCs). Improvements in PPC hardware specifications and the growing numbers of compatible software applications are resulting in an increased (and multi-faceted) user base. Increasing technical capabilities, advanced product features, and a diversified user base are creating new challenges to design online Help systems that can satisfy user needs and requirements effectively.

Natarajan, Prashant. Usability Interface (2004). Articles>Documentation>Help>PDA

Designing Policies and Procedures Information  

The policies and procedures (P&P) developer must address more than format and style issues in designing policies and procedures information. There are at least five levels of design for policies and procedures information. Level 1 concerns the architecture in which the information resides. Level 2 concerns the type of relationship that exists among documents within the architecture. Level 3 concerns the approach used in designing and developing the information content within a policies and procedures document. Level 4 concerns the writing methods to use. Level 5 concerns the various writing techniques for presenting information in units individually and collectively within a policies and procedures document.

Urgo, Raymond E. STC Proceedings (2000). Presentations>Documentation>Policies and Procedures

Designing Responsive Hypermanuals  

The responsive hypermanual is a new method of delivering documentation that orders the contents of an online manual in response to the user’s current task. It uses hypertext modules controlled by an SQL database for managing the development, and presentation of modular documentation to provide a uniquely usercentric system. their needs. When the user asks technical support for help, they delegate the effort of assembling material scattered throughout the document into a meaningful answer.

Lettvin, David W. STC Proceedings (2000). Presentations>Documentation>Interactive

Designing Usable Technical Documents: Why Bother?

Many professionals in the field of technical writing involved in the design of instruction guides, will at some point in their career have experienced some doubt whether their efforts to produce high quality documentation really make sense. Do consumers attach some value to the instruction guides for the products they have purchased? Do they use these documents at all, or are most instruction guides thrown away, together with the packing material of the equipment they come with?

Jansen, C. Indus (2002). Articles>Documentation>Usability

Designing User Assistance for Internet Marketplace Applications Using Server-Side Online Help    

In this article, I examine Internet marketplace applications and the challenges they present to user-assistance design. This examination illustrates the ways in which complex Internet applications, such as marketplaces, force technical communicators to rethink their approach to online user assistance. In the course of this examination, I make a case for a model of user assistance that taps the potential for customizability, scalability, and dynamic content of the technologies that power Internet applications. However, marketplaces are only one example of the type of application that can benefit from this model because it can be implemented for any Internet or intranet application that utilizes dynamic, build-on-the-fly Internet technologies, such as Microsoft Active Server Pages or Sun Microsystem JavaServer Pages. To fulfill our responsibilities to our users, we technical communicators must be willing to expand our skill set by adopting these technologies that allow us to target documentation to user needs.

Whittemore, Stewart. Technical Communication Online (2003). Design>Documentation>Online

Determining the Right Training and Documentation Solution  

Frequently a product has documentation associated with it. Large products may have training and documentation. However, as corporations are 'rolling out' new technology to their staff they are becoming aware that supporting the user through a unified documentation and training strategy, results in fewer problems and faster integration and usage. This paper addresses the process of determining the right solution and an effective design and development process.

Rockley, Ann and Hifary Shirley. STC Proceedings (1997). Articles>Documentation

Determining When to Use Show-Me Helps and Demos  

The availability of powerful yet easy-to-use multimedia tools enables technical writers to consider a powerful new form of embedded user assistance: show-me help. This paper provides an overview of who is currently using show- me help--some current research, some history, and some definitions. It offers some guidance in choosing tools, designing show-me help, and deciding when to include then, concentrating on consideration of your users, potential topics, subsequent releases, and translation. It also suggests how show-me helps can be reused as part of product education and single-sourced into user assistance from the Web. When this information is presented in a conference session, the final part of that session will be a workshop in which a sample show me will be built using the QarbonTM ViewletBuilderTM tool. For this session, you have a choice to watch or do. You can watch as I create a show me for Windows(R) Explorer in this session or you can go to www.qarbon.com, download the demo version of ViewletBuilder, and do the exercises along with me.

Norris Bradford, Annette. STC Proceedings (2005). Articles>Documentation

Determining When to Use Show-Me Helps and Demos

The availability of powerful yet easy-to-use multimedia tools enables technical writers to consider a powerful new form of embedded user assistance: show-me help. This paper provides an overview of who is currently using show-me help--some current research, some history, and some definitions. It offers some guidance in choosing tools, designing show-me help, and deciding when to include then, concentrating on consideration of your users, potential topics, subsequent releases, and translation. It also suggests how show-me helps can be reused as part of product education and single-sourced into user assistance from the Web.

Bradford, Annette Norris. WritersUA (2005). Articles>Documentation>Multimedia>Video

Developing a Documentation Process that Works in a Regulated Environment  

Working in a regulated environment (for example, an ISO-certified company or a company regulated by the FDA) necessarily changes the way documentation is developed and managed. The documentation development process must exist and must meet all of the requirements set by the governing body, yet not be so mired in detail that it overwhelms the writers and managers.

Rupel, Roberta A. STC Proceedings (2000). Presentations>Documentation

Developing a Project Life Cycle for Technical Publications  

Having a technical publications project life cycle (pLC) that parallels an organization's product life cycle (PLC) greatly facilitates its adoption by engineering or development organizations. A technical publications project life cycle relates major documentation project management strategies, tasks, and deliverables to the same model used by technical organizations to control product development in an efficient and cost-effective manner. Some technical organizations perceive the documentation development process as being “intrusive” into the product development process, particularly during the Implementation Phase of the PLC. Communicating a technical publications pLC to these organizations early in the PLC eliminates this misperception.

Le Vie, Donald S., Jr. STC Proceedings (2003). Articles>Documentation>Project Management

Developing a Single-Sourced Online Help System    

The definition of single sourcing continues to broaden in scope since its first mention in The Society of Technical Communication’s 46th Annual Conference publication. As a result, it is becoming increasingly difficult for technical communicators to understand what single source means and, more importantly, choose a definition of single sourcing that correlates with their specific task. One “type” of single sourcing involves reusing information for multiple products. Several developers at IBM have produced a single-source online help system. Unlike other single-sourcing methods that require a significant investment and a high degree of technical experience, these methods are inexpensive and require a moderate, yet creative, technical aptitude.

Vicek, Keith, Phil Menzies and Andre Evans. STC Proceedings (2002). Design>Documentation>Single Sourcing>Online

Developing a Style Guide in the Real World  

Style guides present a series of rules for standardizing writing. Style guide developers run the risk of concentrating too much on these rules, and too little on other factors that may ultimately affect the quality of the documents that are governed by the style guide. I would like to consider some of these other factors in this paper. I’ve drawn this discussion from Battelle’s efforts developing style guides in various industries. Another reason to involve your clients in the development process is to help ensure that the style guide includes the information they will need. For example, we included tips on using Microsoft Word in a style guide that would be used by writers working in Word. Don’t be afraid to be creative when deciding what to include in your style guide; if it gives writers a reason to look something up in the style guide,

Wieringa, Douglas. STC Proceedings (1996). Presentations>Documentation>Style Guides

Developing a Web-Based Tutorial in RoboHelp

The very first thing you should do in developing a tutorial is to be familiar enough with the subject matter that you can write the content.

School for Champions (2005). Articles>Documentation>Writing>Technical Writing

Developing an Embedded Help Solution    

As we grow up, we learn to develop our independence and to ask for help less and less. No wonder that, when confronted with a problem, so few users click the Help button. Standard help systems have several common issues: help is separate from the product; users have to leave the task they are performing to get help, and they return and try to remember what they were doing; users cannot find the required information; users get lost in the help.

Mueller, Paul. Technical Communication Online (2003). Design>Documentation>Help