A Dual Path Approach to Developing Documentation  

The document development process is traditionally viewed as a series of steps along a single linear path. Instead, it is useful to view document development as consisting of activities along dual paths: one product-centered and one document-centered. Isolating a product-centered path reveals how much of your time is spent on activities other than writing--for example, learning about the product. It also highlights the ways in which the documentation is dependent on or shaped by the product.

Igel, Victoria E. STC Proceedings (1994). Articles>Documentation>Methods

Dumbing Down vs. Simplicity

Never assume that describing something in basic, simple, fundamental terms will annoy your audience. Dumbing down is a form of distortion and possibly deception. Simplifying and clarifying are forms of altruistic communication. Find out more about the differences between "dumbing down" and simplifying and clarifying...and how to decide how simple an explanation should be.

Streight, Steven. Blogger.com (2004). Articles>Documentation>Writing>Business Communication

The Duty of Candor in Future Software Documentation

The STC Code for Communicators requires us 'to communicate technical information truthfully...'. Such truthfulness has two related but distinct aspects, honesty and candor. I have never been asked to falsify technical claims in documentation (honesty), but I have occasionally been asked to withhold true claims about software that, if known to users, would surely affect how they interpret or apply that software (candor). The century ahead will increasingly demand user documentation that is candid as well as honest.

Girill, T.R. STC Proceedings (1999). Articles>Documentation

Early Involvement: Writing at Product Design Time  

Lead writing is a process that moves the information development cycle into the product development cycle. Writers and programmers work together from the beginning to produce both code design and supporting information. This process ensures that information developers can actively participate in design, and programmers can contribute to supporting documentation. Both groups gain an appreciation for each other's perspective, expertise, and skills, producing a more customer-oriented product.

Coppola, Carolyn M. STC Proceedings (1993). Articles>Documentation>Writing>Technical Writing

Easy Tools for Documentation Management  

The use of three simple tools can assist the documentation manager, from start to finish, on any new project. A revamped pubs plan, a new concept with engineering worksheets, and a matrix of modularized information are all utilized with a slightly new twist. The Pubs Plan is redefined to help you launch your project with a team approach, identifying issues, and proposing solutions. The Engineering Worksheets list all the critical pieces of information your writers/illustrators need for each component of the product. These pieces of information are then tracked by completion date on an Information Matrix. These documents work together as complimentary management tools that can be easily developed and scaled to the complexity of any project.

Shumate, Chona E. STC Proceedings (1999). Articles>Documentation>Project Management

Editing Guidelines for Software Documentation

Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.

HelpScribe (2008). Articles>Documentation>Editing>Software

Editing Modular Documentation: Some Best Practices

Much has been said about the creation of modular documentation - from content management systems, to information architecture, to delivery forms, to the usability of modular content (content being easier to use, easier to understand, and easier to find), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment.

Corbin, Michelle and Yoel Strimling. WritersUA (2008). Articles>Documentation>Technical Writing>Technical Editing

Editing Your Own Documentation  

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'

Docsymmetry (2003). Articles>Documentation>Editing>Technical Writing

Effects of Documentation Errors On User Perception of Interactive Programs: Background For a Study  

Typographical errors and grammatical blunders affect the aesthetic appeal of documentation, and common belief is that they affect usability too. Many readers, however, seem not to notice such errors unless they are very frequent or flagrant. We thought it would be interesting, and perhaps useful, to test experimentally the effect of such errors on users’ perception of the information and on their performance with the product that the information supports the product.

Grice, Roger A. STC Proceedings (1994). Articles>Documentation>Interactive>Multimedia

Effects of Documentation Errors on User Perception of Interactive Programs: The Experimental Design  

It would be useful to determine how much effect errors in product documentation have on users, if the errors do not seriously interfere with product use. In an effort to start collecting information on this issue, we designed an experiment to explore the reactions of users to a simple interactive program with flawed documentation. We hypothesized that product quality would be judged in part by the quality of the documentation, if the errors in the documentation interfered with task performance. We also hypothesized that some but not all users would be sensitive to documentation errors and would downgrade their rating of the program and the documentation based on these errors. Our experimental design is described in this paper.

Ridgway, Lenore S. STC Proceedings (1994). Articles>Documentation>Usability

The Effects of Motivational Elements in User Instructions    

Should instructional texts be purely technical, with a focus on effectiveness and efficiency, or should they also focus on satisfying and motivating users? Good arguments have been made for paying attention to motivational aspects. But only analyses of existing instructions have been published so far, and guidelines for making user instructions motivational have not yet been studied carefully. This article presents motivational strategies and an experiment to test their effects. The results show that motivational elements have little effect on users’ effectiveness and efficiency in performing tasks, their product appreciation, and their self-efficacy, but they do increase users’ appreciation for the instructions.

Loorbach, N., Steehouder, M., Taal, E. Journal of Business and Technical Communication (2006). Articles>Documentation>Rhetoric>User Centered Design

Egoless Writing: Improving Quality by Replacing Artistic Impulse With Engineering Discipline    

When technical communicators have a strong personal attachment to the publication they are preparing, this attachment may interfere with the design and testing of the publication itself. Documents developed by solo authors tend to be late, buggy, and exceedingly difficult for others to maintain. 'Ego-less' methods---collaborative and structured---break the proprietary connection between the writer and the book; in so doing they permit the most powerful tools of engineering and testing to be used. But they also reduce the satisfactions of the communicator's job.

Weiss, Edmond H. Journal of Computer Documentation (2002). Articles>Content Management>Documentation

Electronic Document Production  

This encyclopedia article provides engineering managers with a detailed overview of the process for developing online documents.

Hayhoe, George F. George Hayhoe Associates. Articles>Documentation>Online

Electronic Documentation Basics

Below you can find a compilation of the most frequently asked questions about electronic catalogs. You will find answers to general as well as to technical questions.

ITEDO Software (2003). Articles>Documentation>Online>Help

Electronic Information Kiosks: A New Online Genre for Technical Communicators  

Kiosk design is an inevitable extension of the development of online documentation. Technical communicators are now frequently being asked by their employers to create such forms of communication. They must learn about kiosks from the new perspectives of their evolving technologies, applications, audience reactions, social contexts, and information design. Finally, technical communicators must begin to view kiosks as an emerging new genre that requires both analysis and creativity.

Shirk, Henrietta Nickels. STC Proceedings (1996). Articles>Documentation>Online

Elegant Documentation  

Blank discusses the benefits of using consistent styles in documentation.

Blank, William. Intercom (2001). Articles>Documentation>Style Guides

Eleven Tips for Writing Incredibly Useful Procedures

Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.

HelpScribe (2008). Articles>Documentation>Policies and Procedures>Technical Writing

The Elves and the Shoemaker—We Don't Wear No Pointy Hats  

When technical communicators are part of a development team, we can do much more than write manuals. Our analysis and communications skills, user perspective can help launch a project team into productivity. We have a unique skill set which enhances the productivity and quality of the development process. By involving us early, we can assume technical communications tasks that developers otherwise perform. This exposure gives us a broader and deeper understanding of that which we communicate. Our involvement means better communication; with users and team members, and in deliverables and development processes.

Mazur, Sue and Jamie A. McCanless. STC Proceedings (1994). Articles>Documentation>Writing>Technical Writing

Embedded Help – Meeting the Needs of Your Users  

Designing and developing an embedded help solution involves several stages. A successful solution starts with identifying user wants and needs. As you sort through these needs, identify common threads and design a solution that addresses these common threads. Consistency, flexibility, and experimentation are keys to developing a successful solution. Your design should be intuitive to use, and should provide users with the options they need. As you design your solution, consider your develop and maintenance requirements. You want the time you invest in the first version of your solution to pay off for future releases.

Mueller, Paul. STC Proceedings (1999). Articles>Documentation>Online>Help

Empirical Proof for Presenting Screen Captures in Software Documentation    

None of the previous studies on screen captures addressed the functions in the framework. There was no empirical research on any of the four functions of screen captures. This article presents our research on these functions. Each section starts with a brief explanation of the function. Next, we illustrate the screen capture designs used to test the function. The remainder of each section explains the setup and results of the empirical study. The article ends with some general conclusions about the functions of screen captures.

Gellevij, Mark and Hans Van Der Meij. Technical Communication Online (2004). Articles>Documentation>Graphic Design>Screen Captures

The Empowered User: A New Approach To Software Documentation  

User empowerment offers a strategy for addressing the software end user's needs. The definition of user empowerment emphasizes a user-driven, informationmanagement oriented approach in response to changes that have taken place in the modern workplace after computers and computer software arrived. Working with software requires a significant shift in thinking and learning, responding to increased abstraction, isolation, and information volumes. Computermediated work demands that users develop new skills and job roles, and that documentation writers develop new techniques for manuals.

Barker, Thomas. STC Proceedings (1994). Articles>Documentation>User Centered Design

The Engineer as Rational Man: The Problem of Imminent Danger in a Non-Rational Environment      

Mine safety instruction manuals and training guides reflect an engineering perspective based on the concept of a Rational Man, a perspective which obsstructs effective risk management.

Sauer, Beverly A. IEEE Transactions on Professional Communication (1992). Articles>Documentation>Risk Communication>Rhetoric

Enhancing Customer Satisfaction by Assuring Documentation Quality  

From the customer's perspective, an important and visible part of a product or service is its documentation. Bellcore's Technical Publications (Tech Pubs) organization uses a Quality Assurance (QA) program that focuses on enhancing customer satisfaction through delivering high-quality documentation. This program emphasizes a 'network' approach to documentation development, whereby technical writers can most efficiently use the support network of QA reviewers and management available to them. The Tech Pubs QA program draws on the needs of clients and the expertise of technical writers to strive to achieve the highest level of quality possible in producing documentation.

Dolese, Cathy and Tara Durkin. STC Proceedings (1993). Articles>Documentation>Quality>User Centered Design

Enhancing Documentation with Video  

Presents guidelines for developing videos from technical material and discusses the process of video production.

Steiner, Leonard T. Intercom (2004). Articles>Documentation>Multimedia>Video

Enterprise Agility: SOX and Enterprise Information Integration  

The intent of Sarbanes-Oxley (SOX) can be characterized as risk reduction: reduce errors, inhibit fraud, and provide shareholders with transparent equal-access to material knowledge. But implementation is principally procedural controls and documentation, under threat of penalty. The vague parts of SOX are where the real leverage lies: principles of intent, and corporate transparency.

Dove, Rick. Paradigm Shift International (2005). Articles>Knowledge Management>Information Design>Documentation