An Overview of Single Sourcing with an XML Content Management System

Creating an XML-based Content Management System to single-source technical publications is as simple as 1 - 2 - 3. OK, maybe it isn't quite that easy, but this article discusses how it can be done.

Sapir, Rick. KeyContent.org (2004). Articles>Content Management>Documentation>XML

Analysis and Resolution of Problems Occurring During the Production of Manuals  

We produce numerous manuals pertaining to telecommunications and, although we routinely devote much energy to reducing the number of problems occurring during the production process, this time we took up the challenge of eliminating the occurrence of problems altogether. Here, we overview the characterisitics of problems occurring at the company, profile their occurrence by process, and review a few corrective measures.

Konno, Toshiaki, Masanori Takagi and Osamu Tomooka. STC Proceedings (1995). Articles>Documentation>Quality

Analyzing Web-Based Help Usage Data to Improve Products  

This paper describes how user assistance can streamline deliverables and improve product design by analyzing usage patterns from server-based content. We can then base decisions about how to improve deliverables on a thorough understanding of how customers use help content to find information and solve problems. This approach enables user assistance to add more value to both our companies and our customers by creating a three-way dialog between user assistance, the customer, and the product team. It also broadens the definition of assistance to include helping to design products that people can use without the need for instructions.

Raiken, Nancy. STC Proceedings (2005). Articles>Documentation>Audience Analysis>Log Analysis

Analyzing Your Users and Needs Before Creating the Help Deliverables; Interview with Nicky Bleiel

In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users.

Bleiel, Nicky and Tom H. Johnson. Tech Writer Voices (2008). Articles>Interviews>Documentation>User Centered Design

The Anatomy of a Help File: An Iterative Approach

This article presents an approach to Help file design that focuses on creating a task-centered user experience and accommodates an iterative development strategy. This methodology allows the introduction of user assistance into early test phases--not only getting earlier validation for its accuracy, but also supporting quality assurance testing by serving as the test scripts for interactions with the user interface. This approach can also be a self-contained strategy--that is, one that allows an iterative approach to user assistance development even if the rest of product development operates on a waterfall model.

Hughes, Michael A. UXmatters (2007). Articles>Documentation>Methods>Help

Animation as Documentation: A Replication with Reinterpretation  

Animated demonstrations are replacing text as the vehicle for documentation, help, and training on new software systems. An animated demonstration is a demonstration of a particular feature or features by a ghost user. The demonstration executes the procedure for performing a task, on-screen, as the user passively watches. Whereas research into the effectiveness of animated demonstrations has produced mixed results, certain patterns of behavior are emerging. The current study replicates the learning advantage offered by animated demonstration and shows that retention is equal to that of a group instructed by text after a one week retention interval. Implications for development of on-line training materials are discussed.

Lipps, Audrey W., J. Gregory Trafton and Wayne D. Gray. STC Proceedings (1997). Presentations>Documentation>Interactive

Anything That Can Go Wrong: Lessons Learned from A Decade of Toolkit Documentation  

Writing software toolkit documentation for programmers is a special challenge and opportunity for technical writers. Compared with writing software documentation for lay users, toolkit documentation is more demanding and exacting. Checking facts and finding tiny errors is like riding a motorcycle through a swarm of gnats. However, for me at least, toolkit writing has opened doors to a larger role and greater input into product design. Engineers treat me like a peer and I get to see into their culture. I know my readers and salespeople need me.

van Oss, Joseph E. STC Proceedings (1999). Articles>Documentation>SDK>Technical Writing

Apple Guide Complete: Designing and Developing Onscreen Assistance

If you've been waiting to give your users more than just onscreen reference information, now you can with Apple Guide, Apple Computer's innovative help delivery system. With Apple Guide, you can produce guide files that actually lead users, step by step, through complex tasks and concepts. If you want to provide task-oriented, context-specific instructions, Apple Guide gives you the ease and flexibility to do so. You'll learn about the complete cycle of designing, scripting, and coding guide files in the four parts of this book.

Apple Inc. (1996). Design>Documentation>Help

Applying Computer Analysis and Design Techniques to Document Component-Based Software  

Facing the challenges involved in developing documentation for component-based software (for example, object-oriented technology, intelligent agents, and distributed computing) requires a documentation strategy based on the same processes and methodologies used by such technologies. These strategies need to be adapted to meet documentation, rather than coding needs. Developing this strategy now, as component-based technology is still maturing, will help technical communicators keep pace.

Bachmann, Karen L. and Ginger Doherty. STC Proceedings (1998). Articles>Documentation>Software

Applying Expectancy-Violations Theory to Online Documentation  

A person usually expects another person to behave according to accepted norms, but how does a person respond to a message that violates his/her expectations? One theory dealing with violations of expectations is Burgeon and Hale's (1) nonverbal expectancy-violations theory. This theory posits that, under certain circumstances, violations of social norms and expectations may be an effective strategy for communicators to achieve the intended communication purpose. Although the expectancy-violations theory focuses on expectations for nonverbal behavior, such as gaze and conversational distance (2), I believe that this theory can also apply to expectations for humancomputer interaction.

Chiu, Yu-Kwong. STC Proceedings (1993). Articles>Documentation>Rhetoric>Online

Applying Object-Oriented Design Concepts to Web Publishing  

This is a story of how one internal project at Sun Microsystems migrated printed user and reference documentation to an internal Web site. The principle architect of this site discusses how she applied object-oriented design concepts to the Web architecture to accommodate many learning styles simultaneously. As important as the successes of this project are its failures, which offer some insight into when and how to use the World Wide Web as a communication vehicle in your overall communication strategy.

Hoft, Nancy L. STC Proceedings (1996). Design>Documentation>Web Design

Applying Performance Technology Principles to Documentation  

Technical writers often produce documentation for products or systems without first determining the best document media or even the necessity for documentation. In some instances, alternatives to documentation may best serve the product or system users. This paper describes the field of Performance Technology and illustrates how to apply principles of Performance Technology to decide when to create documentation.

Hayes, Gabby. STC Proceedings (1996). Articles>Documentation>Technology

Applying Software Development Methodology to Developing Help Systems  

Help systems have become an important part of the Technical Communicator’s repertoire. If we as communicators approach developing help systems in the same way we approach writing paper documentation, we miss the advantages of using software development methodology.

Nurczyk, Susan V. STC Proceedings (1997). Presentations>Documentation>Workflow

Applying the Sensation-Perception Continuum to User Documentation  

The sensation-perception continuum represents the interplay of sensation and perception in everything we think and do. Technical communicators must exploit this continuum by understanding and applying sensory filters and perceptual tendencies in the design and development of information. This paper discuss three sensory filters: thresholds, cocktail-party effect, and sensory adaptation; it discusses four perceptual tendencies: perceptual set, figure-ground relationships, laws of grouping, and goodness of figures.

Coe, Marlana A. STC Proceedings (1996). Articles>Documentation>User Centered Design

Applying Web 2.0 Technologies to Technical Documentation

This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0".

Pratt, Ellis. Cherryleaf (2006). Articles>Web Design>Documentation>Technical Writing

Are We Giving Readers What They Want, in the Way They Want and Need It?

With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past?

DMN Communications (2008). Articles>Documentation>Technical Writing>User Centered Design

Asking Your Users and Doing What They Need: The Story of How Federal Express Ground Operations Revamped Its User Manuals  

Worldwide Communications & Policy is a relatively new department in Federal Express, created to manage communications and produce policy and procedure (P&P) manuals for the largest division in our global company. We asked an outside consultant, JoAnn Hackos & Associates, to evaluate the existing divisional P&P manuals and conduct an audience analysis. We emerged from the process with a plan to change the existing manuals, which tried to be all things to all people, into a collection of audience-specific, task-oriented documents.

Gill, Sadie P., JoAnn T. Hackos, Mary Hartmann, Carol Sowell, and Julian S. Winstead. STC Proceedings (1994). Articles>Documentation>Policies and Procedures

Review: Assessing Quality Documents    

In recent years, an emphasis on quality has emerged in a variety of organizations and in several fields, including technical documentation. Producing Quality Technical Information (PQTI) was one of the first comprehensive discussions of the quality of documentation. An important contribution of the book is in identifying quality as multiple, measurable dimensions that can be defined and measured (previous views of quality identified it more as some elusive thing that could be identified if present but was difficult to articulate and describe). Despite its contributions to the quality discussion, PQTI runs the risk of simplifying the quality process, reducing quality to a simple checklist that information developers can use to develop effective documentation. PQTI fails to address the fluid nature of some aspects of quality: some dimensions that are important in assessing one document may be less important or irrelevant with other documents. Additionally, PQTI falls short of accounting for the larger contextual framing of documents--that the importance of individual dimensions of quality changes depending upon the audience, context, and purpose of the document.This commentary suggests that all quality efforts should be grounded in customer data and user-centered design processes, and that we should learn to better differentiate among quality dimensions, determining those dimensions that are essential to customer satisfaction and those that are merely attractive. Through increased attention to developing the quality of information, organizations can better differentiate their products and services, facilitate greater productivity, and increase customer satisfactions, all significant activities in an increasingly competitive marketplace.

Smart, Karl L. Journal of Computer Documentation (2002). Articles>Reviews>Documentation

L'Association des Professionnels de L'Information et de la Documentation

Créée en 1963 dans le but de regrouper tous les professionnels de l'information et de la documentation, l'ADBS compte plus de 5600 adhérents et se place au premier rang européen des associations de spécialistes de l'information. Ses principaux objectifs sont de: développer les échanges entre professionnels; promouvoir et défendre la profession; diffuser et développer l'application des nouvelles technologies; contribuer au perfectionnement de ses adhérents par l'organisation de journées d'études et de sessions de formation; réaliser de nombreuses publications.

ADBS. (French) Organizations>Documentation>Regional>France

Audacity Tutorial: How to Record and Edit Audio with Audacity

Audacity is a free cross platform multi track audio editing program from Sourceforge.net. It will let you record, edit, and mix an unlimited number of tracks. Audacity runs on Windows (98 through XP), Mac OS X, and Linux.

Guides and Tutorials (2006). Articles>Documentation>Software>Audio

Australasian Online Documentation Conference

Since the very first Australasian Online Documentation Conference in Melbourne in 1998, the conference has developed a reputation as the premier event for technical writers, help developers, Web authors and documentation developers from Australia and New Zealand. Our speaker list reads like a Who's Who of documentation, as we strive to ensure that experts in techniques and technologies are available to share their knowledge and expertise. The conference is also a great place to network with other documentation professionals.

AODC. Academic>Conferences>Documentation>Online

Authoring for Electronic Delivery  

Caterpillar is dramatically changing the way technical, product support information is authored. Book paradigms have been replaced by the more granular Information Element (IE) approach. The new integrated environment utilizes Unix based, TCP/IP connected, ECALS compliant tools on multi-tasking author workstations. Research data, in-process work approved IE's and relational indices are distributed to work group servers. Application software tools include a graphics editor and an interactive, context sensitive, SGML text editor. The environment is managed by a robust file management system that provides file tracking, revision control, workflow sensitive tool launching, burden planning and management reporting capabilities.

Hudson, Dave. STC Proceedings (1993). Articles>Documentation>Online>Help

AuthorIT: Resizing Graphics using JavaScript Code

My client wanted screen shots in their CHM, but the screens were very large thus creating problems when printing a topic. With some help from Dave Gash, I got the large screen shots to open at 50% size, with a function for the user to resize them to 100% either all at once or one at a time. The function also toggled back to 50% at the user's discretion. This solved the problem of large screen shots in the online help, while allowing error-free printing to occur.

Bracey, Rhonda. CyberText Consulting (2003). Resources>Documentation>Software>DHTML

AuthorIT: Time-Saving Techniques Using AuthorIT  

A presentation about techniques one could employ using AuthorIT.

Bracey, Rhonda. CyberText Consulting (2005). Presentations>Documentation>Software