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 Help

This site offers material on a wide range of HTML-related topics. We hope that with this site as a reference, you will be able to create Web sites that can be used by every person on the Internet, regardless of browser, platform, or settings.

Web Design Group, The (1999). Design>Documentation

HTML Help: Transition Without Fear  

You need not be a programmer to begin producing effective, attractive HTML Help or Webpages. You can use pubiished tempiates andauthonng toois and study an existing page’s HTML code to heb you produce pages whiie you learn. Templates allow you to add your content to existing skeleton pages. You can also use an HTML or HTML Heip authoring tooi to create your help. HTML Heip authoring tools aiiow you to add WinHeip-like functionality and ~eamnce to your HTML Hefppages. Using your browser and a text editoc you can study HTML code frum an existing Webpage. Using these methods, you can learn HTML while already producing effective Heip.

Lambert, Twyla Beth and J. Suzanna Laurent. STC Proceedings (1997). Presentations>Documentation>HTML

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

Implications for Writers Documenting Object-Oriented Projects  

Object-oriented (OO) projects bring with them new technology and new processes. While programmers focus on the OO methodologies governing design and implementation of program code, writers must struggle to adapt to a very different kind of development cycle. To avoid chaos, development teams must explicitly define their processes from the start.

Berry, Robert R., Karen L. Mobley and Kathryn L. Turk. STC Proceedings (1994). Articles>Documentation>Software

Implicature, Pragmatics, and Documentation: A Comparative Study    

This study investigates the link between the linguistic principles of implicature and pragmatics and software documentation. When implicatures are created in conversation or text, the listener or reader is required to fill in missing information not overtly stated. This information is usually filled in on the basis of previous knowledge or context. Pragmatics, the study of language use in context, is concerned with the situational aspects of language use that, among other things, directly affect implicatures required of the reader. I investigate how two manuals for the same software product can be analyzed on the basis of implicature and pragmatics. One is an original copy of the documentation that came with the product, the other an after-market manual. Results show that the aftermarket manual requires far fewer implicatures of the reader and does a better job of providing pragmatically helpful information for the user.

Wright, David. Journal of Technical Writing and Communication (2007). Articles>Documentation>Rhetoric>Technical Writing

The Importance of Software Documentation Standards

The look and feel of a help system can differ greatly from one product to the next, as can the writing. So how can the technical writing community emphasize the importance of software documentation standards and create a more unified help experience that users can adapt to?

Helpscribe (2008). Articles>Documentation>Standards>Software

Improving Document Quality Through Customer Visits  

In an effort to improve the quality of our documentation, our Information Development department personally visited over 80 of our customers in 10 different locations across the United States. Our goal was to find out what we needed to do to create documentation that would satisfy our customers' needs. We came up with a process for planning our visits, gathering the information from our customers, implementing their requirements, and increasing communication with them. From the visits, we not only made changes that immediately satisfied our customers, but we created an environment for them to work with us as a team.

Lass, Laura W. and Wendy L. Reed. STC Proceedings (1993). Articles>Documentation>Quality>User Centered Design

Improving Documentation Through Customer Feedback: A Case Study  

By soliciting and receiving customer feedback, writers learn how customers use existing documentation and what additional information customers may need. In May 2001, we began a formal process of gathering customer feedback for the IBM WebSphere Commerce Suite product. The first phase of this process involved two main initiatives: creating and promoting a documentation questionnaire for customers; creating and working with an internal test team that acted as customers. Feedback allowed us to determine which information strategies helped customers meet their business needs, and which areas we need to concentrate on in future releases.

Heximer, Erin and Lisa Wu. STC Proceedings (2002). Articles>Documentation>User Centered Design

Improving Documentation with Learning Techniques  

It is important to recognize that because we all differ in our experience and background the learning process is different for each of us. Consequently, in our documentation we should by to put users on an equal footing by, for example, clearly and exactly defining terms we use and including a glossary. We can also put everyone on an equal footing by using 'bridges to understanding,' from analogies, examples, and metaphors to mnemonic strategies. For overall comprehension, we can employ 'frameworks,' from conceptual maps to road maps, that give patterns of meaning to what we say.

Livingston, Dick. STC Proceedings (1993). Articles>Documentation>Instructional Design>Glossary

Improving Medical Treatment Procedures  

Technical writers should be alert for opportunities to improve documentation in one technical field by using appropriate techniques from other fields. In this paper, the author presents ways of improving medical treatment procedures by using elements from engineering procedures, including introductions, safety sections, warnings, conditional (branching) statements, and notes.

Gibbs, Judith M. STC Proceedings (1996). Articles>Documentation>Biomedical>Policies and Procedures