The Hidden Power of the Online Manual

Writing software manuals is boring, isn't it? We often think, "My software is easy to use. The user interface is intuitive. Why should I waste so much time writing documentation which nobody will read anyway?" Sometimes it's true. I've never read the WinZip or Internet Explorer manuals. Everything seems clear enough without further explanation. Nevertheless, even if your manual isn't being helpful to your software users, it may be helpful to you. Publish your manual online and turn its hidden power into a real benefit for your business.

Crane, Dennis. Dr. Explain (2006). Articles>Documentation>Online>Technical Writing

How Design Documents Enhance Information Product Development Process Quality  

Panelists from LSI Logic Storage Systems review their company's approach to enhancing process quality by using design documents as process enforcement and project-planning tools for planning the development of information products (IP). Hear how effective planning solves problems that occur during the IP development process and how capturing the planning elements in design documents helps solve role-based problems for developers, editors, and managers. Discuss the many problems design documents help project teams solve: they help developers solidify the IP development task sequence, they help editors define the rhetorical context, and they help managers reduce the cost of rework.

Burroughs, Dia H., Randy Clark, Sylvia McCombs and Tony Washington. STC Proceedings (2004). Articles>Documentation>User Interface>Workflow

How to Approach a Systems and Programming Documentation Project  

The biggest concern in software development environments is the retention of programmers. What they are really concerned about is the knowledge drain. These organizations know they need to capture this knowledge, but they do not want to do it themselves. They are turning to the writers who have always written the user manuals. These writers, most having no systems or programming background, must develop internal documentation for use in a programming maintenance environment. They do not know where to begin. This paper outlines a methodology for developing systems and programming documentation for programmers in a maintenance environment.

Glick-Smith, Judith L. 'Judy'. STC Proceedings (1998). Articles>Documentation>Programming

How to Choose a Good Instructional Book about OpenOffice.org

If the success of an open source project can be measured by the number of third-party books about it, then OpenOffice.org is thriving. Not only is OpenOffice.org represented by a dozen books and pieces of training material on Amazon.com, but interest in OpenOffice.org is widespread enough that each of the books is geared to a slightly different audience. This article gives an overview of four of the current OpenOffice.org books, ending with a suggestion of which to buy for your own needs.

Byfield, Bruce. IT Manager's Journal (2004). Articles>Documentation>Software>OpenOffice

How to Convince Others of the Importance of Documentation

If you've been a technical writer for long, chances are you've had to convince someone of the importance of documentation. It just comes with the territory. People often don't see the value of writing technical manuals. So how do you convince them?

HelpScribe (2008). Articles>Documentation>Collaboration

How to Create User-Centered Documentation, Interview with Joe Sokohl

In this podcast, Joe Sokohl explains how to create user-centered documentation by contacting, observing, and interviewing users to gather information about what types of information they use and the help deliverables they actually want.

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

How to Plan On-line and Paper Versions of a Software Manual

On projects for which you must produce both on-line and paper documentation, there are many things you should consider before you start.

Kozuma, Bruce. Boston Broadside (1991). Articles>Documentation>Project Management>Planning

How to Publish a Great User Manual

When was the last time you curled up in bed with a really good user-manual just for the sheer joy of reading it? Never? Think that is some immutable law of nature, like the one that dictates all textbooks must be dull as dirt? 'Tain't so, McGee.

Tognazzini, Bruce. Nielsen Norman Group (1998). Articles>Documentation

How to Stop Writing Documentation and Start Working for Your Users  

How do you stop writing documentation and instead give people the information they need to use a product? You start by understanding your users: their level of expertise, the tasks they need to accomplish, and the problems they are likely to run into. Then you can help them do their work by presenting the information from their point of view and focusing on real tasks, rather than product functions. With this background, you can develop information that is easy to understand, easy to find, and visually effective.

Bergen, Karen A. STC Proceedings (2001). Articles>Documentation>User Centered Design

How to Use Six Sigma to Improve Documentation  

Six Sigma is a tool you can use to ensure that your documentation is satisfying customer needs and expectations. The three case studies provided demonstrate ways in which Six Sigma has helped us make our documentation more effective by finding out more about the customer and getting the customer more involved. This paper does not teach Six Sigma methodology or its statistical background.

Beard, Lori and Erin Beal Welch. STC Proceedings (2002). Articles>Documentation>Methods

How to Write Instructions

These guidelines are written primarily for people who are not technical writers. If you are new to technical writing, you will probably find these instructions useful.

Unwalla, Mike. TechScribe (2003). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation

Write a really bad manual and you’ll not only lose users, you’ll create ex-users who go out of their way to tell others how bad your application is. Documentation matters.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Donald Knuth Was Wrong

In the continuing absence of maturity in the software world, it’s the documentation that has to treat the tool-user with respect. Which is a further argument against Knuth’s Literate Programming. Since it’s all too common to see software toolmakers treat tool-users with short shrift, it’s a useful caution to have the ’software is written in one corner and documented in another’.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Four Rules and an Axiom

Keeping to the four rules articulated here—and never forgetting the axiom—will definitely improve your documentation. If nothing else, recognizing and observing these rules will raise the status of documentation and the people producing it. And they’ll use that raised status in at least two ways.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

HTML-Based Help: A Convergence of Two Solutions  

IDX Systems launched two separate HTML-based help authoring efforts simultaneously. The results were two very different HTML-based help solutions. One solution emphasized thorough and complete information while compromising accessibility. The other solution emphasized accessibility while compromising thoroughness and completeness. In both cases, the compromises were forced by the limitations of current web technologies. The two writing efforts have now been merged into one solution that uses HTML, database technology, and Active Server Pages.

Johnson, Wayne and Fritz Garrison. STC Proceedings (1998). Articles>Documentation>Online>Help

Hypertext for Handling Conceptual Material

Turning 'help' systems and 'browsers' into robust structured-document viewers: the DocBrowser.

Hoffman, Michael. Hypertext Navigation. Articles>Documentation>Web Design>Web Browsers

I Know What You Need to Know: Is that User Centered Documentation?

Quality management is forcing technical communicators to meet the challenge of writing user-centered documentation. Adequate preparatory work would be to categorize potential users according to experience, knowledge, tasks to be performed, and other use-relevant features. Users' requirements and requests should then be incorporated into the document's design.

Bock, Gabriele. TC-FORUM (1999). Articles>Documentation>User Centered Design

I RTFM, But It's Still Greek to Me

You've heard it from your geeky friends: RTFM, politely translated as 'Read the Freaking Manual.' But what if the manual is unreadable? It's difficult enough to upgrade a motherboard or install new hardware, but it can become a disaster when the only help you've got is a poorly translated, barely legible photocopied manual loaded with vague definitions and unhelpful diagrams. And all too often, that's the way it is.

Krasne, Alexandra. PC World (2001). Articles>Documentation>Technology

IBM User-Centered Design for the Documentation Designer  

The user-centered design of documentation is an aspect of product design that has often been under-emphasized. Difficulties inherent in documentation design include obtaining user, feedback to high-level design objectives; extracting user. feedback specific to a product’s documentation. rather than to the product as a whole; and managing the various resource constraints inherent in product development. IBM User-Centered Design offers a solution to these difficulties by employing a set of user feedback methodologies from which the documentation designer, a member of a multidisciplinary design team, extracts pertinent data to set design objectives and follow through to low-level designs.

Righi, Carol and Lynn VanDyke. STC Proceedings (1996). Articles>User Centered Design>Documentation>Technical Writing

Ideas on Cooperation Between Suppliers and Users Regarding Documentation

Documentation, operators’ manuals, maintenance instructions, etc, can never be perfect and satisfy all users. The organization of the documentation, particularly for large systems, will never suit all users and there will always be some errors present. This means the supplier and the user need to cooperate in various ways to avoid the fatal consequences of errors and misinterpretations, and for the improvement of documentation over time.

Rullgård, Åke. TC-FORUM (2001). Articles>Documentation>User Centered Design

Identifying Critical Content - An Alternative to the Outline  

This paper presents a practical, easily applied approach for designing information from the reader’s perspective. It also contrasts the traditional outline with the new approach. The Corporate Standard: Functional Thinking and Writing is a flexible and reader-oriented methodology that allows writers to get started quickly and readers to find and understand the information they need quickly.

Murphy, Stephen W. STC Proceedings (1999). Articles>Documentation

Impact of Multimedia on Online Documentation  

Multimedia is commonplace in entertainment and the Internet is proliferating the use of multimedia in electronic materials. Online documentation has traditionally been composed of text and some graphics. The proliferation of Intranets and online documentation is pushing the acceptance of multimedia in reference and procedural materials like Help. However, there is little research on the value of multimedia in online documentation nor its effective use.This paper describes an exploratory study done for a Master of Information Science thesis to determine the impact of multimedia on online documentation.

Rockley, Ann. STC Proceedings (1998). Articles>Documentation>Online>Multimedia

Implementing a Document Control System  

Document control is a major component of any quality system. To implement a document control system, first establish Policies/procedures for generating, approving, issuing, and revising documents. The next step is to design and implement forms and a filing system/data base for managing quality documents. Teamwork and established guidelines can help ease the complexities of implementing a document control system.

Matthews, Diane L. STC Proceedings (1994). Articles>Documentation>Content Management

Implementing Help Systems for Java Applications  

Technical communicators are facing a revolution in how we develop online help for software applications. No where is this more apparent than in the development of help systems for applications written in Java. Sun Microsystems, Inc., expects to roll out JavaHelp in the early part of 1998. Until JavaHelp arrives, technical communicators will have to find creative ways to implement HTML help systems for Java applications. The best news is that we have some standards to follow, like HTML, and some methods for browsing HTML help today. The key is to develop scalable help systems designed with the future in mind. This paper discusses some ways you can create HTML help content that works with your applications today and tomorrow.

Colvin, Richard D. STC Proceedings (1998). Articles>Documentation>Online>Help

Implementing XML: A Writer's Perspective  

In the cover article for Intercom's special issue on XML and HTML, Conlin discusses how the implementation of XML affects writers of documentation.

Conlin, Karen E. Intercom (2002). Articles>Documentation>XML