Living Documentation: The Future of Technical Writing

Living documentation is documentation that does not cease to be developed until the product ceases to develop. Living documentation can be produced at any time in multiple formats. The book, web pages and online help would continue to be developed as long as that development either solves inaccuracy or increases product usability and customer satisfaction.

Hewitt, John. Writer's Resource Center. Articles>Publishing>Documentation>Online

The Logical and Rhetorical Construction of Procedural Discourse     

A very useful perspective for understanding procedural ('how to') discourse and for writing better procedures is to view procedures as a framework of actions and states. The states include desired (goal) states and unwanted states; the actions are user actions, system actions, and external events. This framework underlies all kinds of procedural discourse, including streamlined-step procedures, the model that predominates in online help systems. The components that make up streamlinedstep procedures are best understood as combinations of actions and states. Procedural discourse is also highly rhetorical in nature. We can see the rhetorical implications of actions and states in the various models of procedural discourse, and in specific strategies that writers implement. Because of its terse and rigid nature, the streamlinedstep model is not well suited for certain rhetorical strategies and cognitive goals, and so while recognizing the efficiency of the streamlined-step model, writers should not neglect more

Farkas, David K. Technical Communication Online (1999). Articles>Documentation>Rhetoric

Lovely DITA, DocBook Fades?  

Makes the case for DITA and provides a compare-and-contrast of DITA and DocBook.

Dumbill, Edd. Intercom (2006). Articles>Documentation>Standards>DITA

Low-End Online Documentation Viewing Systems: Why and How  

Online documentation is now widely accepted for its convenience and cost savings. However, some small, non-Windows shops find very few offerings in the market place for online documentation software.

Sonnenberg, Beth Apple. STC Proceedings (1995). Presentations>Documentation>Help>Online

Mac OS Help

Online help facilities are an important part of any software product in today's marketplace. Apple has a number of technologies specifically designed for providing both convenient to use and easy to understand online help. Interested developers can take advantage of these technologies and use them to build online help facilities into their own products. This page provides an overview of the current Apple help technologies along with links to other related resources.

Apple Inc.. Resources>Documentation>Online

Maintaining Documentation Across Several Languages  

As more companies move into markets beyond their borders, many technical communicators are faced with this new situation of having to deal with more than one language for their documentation The costs and time involved in localising and maintaining these documents can be substantial. This paper briefly discusses some of our experiences and gives some pointers on how a technical communicator can ensure the successful maintenance of documentation across several languages.

Pereira, Reynold G. and Jennifer O'Neill. STC Proceedings (2003). Articles>Documentation>Localization

Maintaining Quality Control in Documentation  

If all of us were more focused towards quality in our lives, we would have it in abundance. We would have higher satisfaction levels and therefore, have lesser complaints. This paper presents cases and reasons why user manuals and guides are not up to the expected standards. Do we need to go beyond checklists before shipping a document? Are reviews and checklists sufficient? This paper briefly talks about the measures that we could take to ensure that a good document is delivered.

Singh, Neelam. STC Proceedings (2002). Articles>Documentation>Assessment

Making Documentation Accessible to Users With Disabilities  

Good documentation takes into account the needs of people with disabilities. Such documentation is termed 'accessible' and provides support for the assistive technologies used by people with disabilities. For example, accessible documentation provides a text equivalent for each graphic element, such as a picture, flow diagram, or icon. This provision is necessary for users who rely on screen readers to read the documentation.

Chappell, Gail B. STC Proceedings (2003). Articles>Documentation>Accessibility>Technical Writing

Making Help More Human, and Other Discussions

Discusses a number of trends in the technical writing world, particularly the need to make help more human by adopting conversational tones and addressing the angry/frantic state of the user.

Johnson, Tom H. and Heidi Hansen. Tech Writer Voices (2007). Articles>Documentation>User Centered Design>Help

Making Manuals Obsolete: Getting Information out of the Manual and into the Product    

Users loathe reading the operating manuals that accompany new equipment. Manuals often sit unused on a shelf, far from their targeted audience, while the costs of technical support soar. This article promotes integrating information traditionally found in printed manuals into the product itself and reports the experience of a design team in developing an easy-to-use product requiring minimal printed documentation. As part of design teams, technical communicators can advocate both reducing the amount of information required to operate a product and making the information immediately available when needed. These strategies can produce increased customer satisfaction and lower post-sales support costs.

Millar, Carol. Technical Communication Online (1998). Design>Documentation>User Interface

Making Online Help Helpful -- Perspectives of Professionals and Users  

This paper reviews research done in online help information, analyses different views on it from the perspectives of professionals of technical communication and end-users, and suggests ways to solve problems.

Li, Yue. STC Proceedings (2003). Articles>Documentation>Online>Help

Making Online Information Usable

So you follow all the standards and guidelines, but suffer nagging questions about whether anyone can and will use the help you’ve just written. Or management wants you to move your printed documentation online, but you wonder whether that’s really best for your users. In the course of our consulting work, we’ve done dozens of usability studies that focus on how people use a variety of printed and online documentation, including manuals, help, cue-cards, and wizards. We’d like to share some of our results and observations, in hopes that this will help you make more informed design decisions.

User Interface Engineering. Articles>Usability>Documentation

Making Product Information an Integral Part of the Development Process  

Document inspections formalize the document review process and encourage the full participation of technical developers in the documentation development process. A document inspection consists of three parts: a briefing meeting, a desk review, and a recording meeting. At the briefing meeting, you state your requirements for the inspection process. During the desk review, the technical developers review your document. At the recording meeting, you review the comments made by the technical developers, and as a group decide on appropriate resolutions.

Hildebrand-Lund, Ruth. STC Proceedings (1996). Articles>Documentation>Workflow>Technical Writing

Making Sense of Step-by-Step Procedures    

Procedural instructions that consist of only a sequence of steps will probably be executable, but nevertheless 'meaningless' to users of technical devices. This paper discusses three features that can make procedural instructions more meaningful: adding functional coordinating information, adding information about the use of the technical device in real life, and adding operational information about how the device works. The research literature supports the effectiveness of the first feature, but offers little evidence that real life elements enhance understanding of instructions. As for operational information, the research suggests that users are willing to read it, and that it contributes to better understanding and performance in the long term, but only if it is closely related to the procedure. As a conclusion, we propose a theoretical framework that assumes three levels of mental representation of instructions: syntactical, semantic, and situational.

Steehouder, Michael F., Joyce Karreman and Nicole Ummelen. ACM SIGDOC (2000). Articles>Documentation>Rhetoric>Technical Writing

Making Web-Based Online Help Accessible: A Case Study  

Accessibility is about providing successful access to information, and the use of information technology by people who have disabilities. The IBM® WebSphere® Commerce development team adopted IBM’s mandate to make its software accessible, and achieved a high level of accessibility in its release of the IBM WebSphere Commerce, Version 5.4, suite of products. Continuing with the next release, the WebSphere Commerce development team strove for an even higher level of accessibility. This paper discusses some of the experiences and lessons learned from making WebSphere Commerce online help and software accessible. It examines some of the most common issues from the User Experience, Information Development, and Test perspectives.

Bot-Roche, Diba, Frances Mullally, Vijay Sivashankar and Donna Sutarno. STC Proceedings (2003). Articles>Documentation>Accessibility>Help

Man, Machine and Technical Communication

Producing technical documentation is a wide-ranging process. It varies from company to company and from project to project. Often we are dealing with an extensive, multilingual project, which is going on simultaneously in many countries. Documentation must be consistent and systematically produced and updated: it works as a base for multilingual user documents from installation guides to marketing material. Documentation takes into consideration the language and cultural differences of various target groups as well as differences in information perception and learning. Forms of communication also vary: part of it is in traditional paper format, but electronic formats and multimedia are being used more and more.

Varantola, Krista. University of Tampere (1999). (Finnish) Articles>Documentation

Manage the Document Life Cycle for the Important Documents on Your Project  

Not all documents require a full lifecycle, but if you understand the nature of building documents, you will be better able to plan for the time required to complete them successfully.

Mochal, Tom. TechRepublic (2005). Articles>Project Management>Documentation

Management Activities for Achieving Organizational Change and Improvement  

Viewing your documentation or training group as a business entity is an important first step toward enabling organizational change and improvement. The actual business status of your organization - a company unto itself a profit center in a larger company, or a cost center in a larger company - matters not. It’s your view of things that will put you on the road to operating your group as a business.

Currie, Cynthia C. and Thomas J. Vallone. STC Proceedings (1996). Careers>Documentation>Management

Managing a Company-Wide Policies and Procedures Project  

It takes skills in three different areas to manage a company-wide policy and procedures project. First, people must be organized and motivated to participate. Executive support is critical here. And the persons actually performing the tasks must be the ones to document it. Second, the project must be clearly defined and tracked. The document creation and review process must be structured simply, to take full advantage of the documentation team’s limited time. Finally, the information published must be accurate and controlled. Work processes should be analyzed before the procedures are documented, and published procedures must be distributed to specified manual holders.

Creps, William B. STC Proceedings (1996). Articles>Project Management>Documentation>Policies and Procedures

Managing a Documentation Project from Both Sides of the Atlantic  

Most of us struggle every day with keeping the lines of communication open between developers, subject matter experts (SMEs), customers, and writers. Sometimes you can circumvent these difficulties by simply walking upstairs or across the hall and chatting with the appropriate person. But what happens when it's not a staircase or hallway separating you but a very large ocean? The best way to keep an overseas project on track is to put together a writing team in the most convenient location; meet at least once with the development team; and set up your communication channels early.

Morgan, Sharon. STC Proceedings (1998). Articles>Documentation>Collaboration>Online

Managing and Documenting Your Project, XML Style

Here are links to the listings described in Managing and Documenting Your Project XML Style.

Fisher, Timothy. XML Journal (2003). Articles>Documentation>Project Management>XML

Managing Content in Regulated Industries  

Global organizations, particularly those in regulated industries, have to juggle a wide range of competing priorities. They must have thorough documentation, clear internal and external communication, audience-appropriate marketing materials and many types of “fine print” carefully crafted. That means that many different departments, sometimes spread across geography, must be involved in all layers of the business. In a regulated field, multiple touchpoints mean multiple opportunities for triggering a regulatory error.

Giovanis, Kristen. tekom (2006). Articles>Documentation>Localization

Managing Customer Feedback on User Documentation

Customer-feedback concerning product documentation is an 'artifact' of value. Product/project management depends on documentation groups to play an active role in closing the feedback acceptance and incorporation cycle to the best satisfaction of the sending-customer.

Parameswaran, Jaya. Usability Interface (2005). Articles>Documentation>Usability