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 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 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

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

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

Authority and Audience-Centered Writing Strategies: Sexism in 19th-century Sewing Machine Manuals    

This article examines audience-centered writing strategies in two very early sewing machine manuals and considers the interplay between such strategies and sexism in technical writing. It considers the difference between non-sexist and gender-neutral writing, and concludes that avoiding sexism in technical writing is difficult at best—and perhaps impossible—in any society that assigns work (and correspondingly, technologies) for use according to the gender of the user.

Durack, Katherine T. Technical Communication Online (1998). Articles>History>Documentation

Automating Documentation Generation

The advent of automatic generation tools, that could automatically generate the information was a major step in the creation of more accurate documentation and it held the promise of saving time and money.

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

Automating Production with WebWorks AutoMap

WebWorks AutoMap is an extremely useful tool for performing unattended documentation builds. Out of the box, AutoMap can generate reasonable documents. By adding the power of scripting, the results can be amazing.

Bate, Simon. Carolina Communique (2006). Articles>Documentation>Software>Word Processing

Automation Techniques in Documentation    

Data, which is readily available at the click of a mouse, is the buzzword in today’s world of rapid technological advancements. Looking at it for the first time, it may seem that the easy availability of data leaves no room for automation techniques, but as a matter of fact the process of documentation is clearly witnessing a sharp inclination towards automation. Though these automation techniques are already in place, it would take some time before they could be accepted by the masses.

Wadhwa, Vikas. International Journal for Technical Communication (2006). Articles>Documentation>EPSS

Avoid the SOX (Sarbanes-Oxley) Documentation Nightmare With These Five Tips

The Sarbanes-Oxley Act has been called the most comprehensive reform of corporate law since the Securities Exchange Act was passed in 1934. The effects of SOX are far reaching. Its provisions govern actions by management, audit committees, and boards of directors of public companies. Like it or not, Sarbanes-Oxley is here to stay. Its impact on IT departments is major and growing. The reaction of many IT groups is to document everything in sight in an attempt to cover themselves. In the end, this can be counter-productive, expensive and wasteful.

D'Amico, Vin. IT World Canada (2006). Articles>Documentation>Regulatory Writing

Balancing Paper and Online: Integrating CD-ROM into Document Libraries  

A panel of industry experts provides an overview of the CD-ROM publishing process—and its business issues, for technical communicators who are responsible for implementing CD-ROM publishing in their organizations. The panel will also discuss guidelines for integrating print and CD-ROM documents into a complete user support library, while still gaining the economies of CD-ROM publishing.

Gale, John, Stephanie L. Rosenbaum and Pamela Sansbury. STC Proceedings (1995). Articles>Documentation>CD ROM

Barriers and Approaches to Reviewing Documentation

This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here.

Boston Broadside (1997). Articles>Documentation>Editing>Collaboration

Baselining Documentation on a Wiki

The dynamic nature of wikis can cause a few headaches when you need to baseline documentation that's on a wiki to correspond with the release of your product. This blog post looks at some ways in which you can try baselining wiki content.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

Beginning a Documentation Project

Starting a documentation project is like opening a box filled with puzzle pieces and trying to figure out if you have all the right pieces for the right picture without knowing how many pieces make up the puzzle and what the picture looks like.

Taylor, Vicki M. Suite101 (2001). Articles>Documentation

Behringer Multitrack Audio Mixer

Introduces how to perform multimedia audio mixing and editing using a Behringer multitrack mixer.

Pratt, Andrew and Dave Long. Studio for New Media (2004). Articles>Documentation>Multimedia>Audio

Benefits of Using a Professional to Write User Documentation

Studies have shown organisations value the following benefits: overall organisation, the sales team, and documentation meets the customer's requirements.

Cherryleaf (2003). Articles>Writing>Professionalism>Documentation

The Best of Both Worlds: Combining Usability Testing and Documentation Projects  

Describes two cases in which usability testing and documentation projects were performed in conjunction with one other. It describes how usability testing affected the design and content of the documentation and how follow-on usability studies added significant new data not revealed in the initial tests.

Kantner, Laurie, Stephanie L. Rosenbaum and Connie Leas. Tec-Ed, Inc. (1997). Articles>Documentation>Usability

Best Practice Flare: High Definition PDF

Having introduced the concept of high definition PDF's output straight from Flare's source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.

Tech Write Tips (2006). Articles>Documentation>Software>Madcap Flare

Review: Best Practices in Policies and Procedures  

Page's book makes the first attempt to open the door to examples of tables of contents of P&P from a variety of organizations. He also makes an admirable attempt to position and show the P&P analyst/writer as more than a scribe, as a leader who adds value by formulating best P&P practices in collaboration with others for their organization.

Urgo, Raymond E. Technical Communication Online (2003). Articles>Reviews>Documentation>Policies and Procedures