Creating User-Friendly Documentation

We often hear that users do not read documents. To lure readers into reading our documents, we must make documents user-friendly.

Bhatia, Neeraj. Indus (2002). Articles>Documentation>User Centered Design>Technical Writing

Using DocBook to Generate WebHelp

A brief tutorial on creating cross-platform WebHelp (similar to that produced by RoboHelp) using DocBook.

Nesbitt, Scott. DMN Communications (2004). Articles>Documentation>Help>DocBook

A Critical Assessment of the Minimalist Approach to Documentation  

Carroll's (1991) minimal manual has been considered an important advance in teaching first-time users the basics of computer programs. Unfortunately, it is not very clear what minimalism really means. Practitioners, for example, will find it difficult to create their own minimal manual because the principles of minimalism have not been described in enough detail (see Horn, 1992; Tripp, 1990). It is also not yet settled that a minimalist approach is the most effective one because critical experiments have hardly been conducted. This study therefore closely examines the minimalist principles and claims. This paper describes the basic ideas of minimalism, its design principles and how they can be operationalized. A parallel is drawn between a minimalist and constructivist perspective on learning and instruction. Like minimalism, constructivism places a high value on experience-based learning in context-rich environments. Like minimalism, it stresses the need to capitalize on the learner's prior knowledge as much as possible. And like minimalism, constructivists urge learners to follow their own plans and goals, to make inferences, and to abstract principles from what they experience (see Duffy & Jonassen, 1991, 1992). An experiment is reported that examines the claims of minimalism. Strong and significant gains on several factors were found, all favoring the minimal manual over a control (conventional) manual. The discussion points to several issues that minimalism has yet to address.

van der Meij, Hans. ACM SIGDOC (1998). Articles>Documentation>Technical Writing>Minimalism

Critical Elements in the Design of Help and Hypertext Systems  

The demand for help and hypertext systems has created a problem for many documentation departments, particularly those in smaller companies and inexperienced in creating these forms of online documentation. The scarcity of existing literature compounds this problem. This document provides writers in small companies with limited resources some suggestions to facilitate hypertext project management, planning, design, editing, and usability testing. Also discussed is how to select a hypertext package.

Wasserman, David C. STC Proceedings (1993). Articles>Documentation>Hypertext>Help

The Critical Role of Local Support

Adapting new equipment to your complete array of jobs, and leveraging your new investment to help your business grow and become more competitive, is part of an ongoing process that is much more important that the initial implementation. It's a process that requires an on-going partnership and several levels of support from your technology vendor-- beginning with basic maintenance and repair and optimally evolving to a true interactive partnership.

Raus, Bob. On Demand Journal (2004). Articles>Documentation>Help

Cross-Cultural Transformation of Technical Documentation for the Chinese Market

Technical authors can compile technical documentation of high quality for a foreign market only if they are able to respect and understand the foreign culture.

Just, Stefan. TC-FORUM (2000). Articles>Documentation>Localization

Cross-Referencing Step Numbers in Word

If you are like most technical writers, your procedures have automatically numbered steps (whether in tables or text), Microsoft Word provides two relatively simple ways for you to cross-reference a step number.

McConnell, Gloria. Usability Interface (2004). Articles>Documentation>Software>Microsoft Word

Cultural Influences on Technical Manuals    

Budget and time constraints often force technical communicators to produce manuals that are less than effective. One reason is the time they take to analyze their document's users. Normally, user analysis involves demographic, or organizational, or psychological approaches or combinations. Rarely will they evaluate the culture of the user and determine what that means for developing the document. Typically, localization will edit the document for cultural elements, but that is an expensive and time-consuming process. This article discusses the cultural elements in developing a document and shows, through a comparison of two mythical cultures, how the document will differ when organized for those two cultures.

Warren, Thomas L. Journal of Technical Writing and Communication (2002). Articles>Documentation>Cultural Theory

Current Trends in Technical Communications

Many technical writers are developing usability skills and leveraging them to help improve the product interface. Help is being delivered within the interface itself. Drop-down lists of topics related to an interface component, hint text below a GUI field, and other such embedded user assistance models allow users to get help without leaving the application interface.

Haiss, Craig. HelpScribe (2008). Articles>Documentation>TC

Customer Partnering: Data Gathering for Complex Online Documentation  

Technical communicators today must document complex applications used in complex environments. Information about users and use models is important under these conditions, especially if documentation will be presented online. Customer partnering, a method of information gathering that supplements surveys, contextual inquiries, usability testing, and interviews, provides a way of involving the users of complex applications in the design of information delivery systems. We used this method to help a client gather important information about user and use models and design a new information library for complex server computer systems.

Hackos, JoAnn T., Molly Hammar and Arthur Elser. ComTech Services (1997). Articles>Documentation>User Centered Design>Collaboration

Customer Satisfaction Lessons Learned from Building Furniture with Wordless Documentation  

Documentation and package design play a major role in customer satisfaction. The author tested three sets of wordless documentation by building pieces of furniture from three different manufacturers. While the construction methods, packaging, and wordless documentation methods were on the surface very similar, small differences had a significant impact on the usability of the instructions and the overall customer satisfaction with the documentation and the product. Decisions that were handled differently included visual verification of parts, whether or not extra hardware was provided and how it was provided, the appropriateness of the hardware, the quality of the hardware, the need for additional tools, and the care evidenced in packaging and labeling of parts. From these experiences, she makes recommendations for enhancing customer satisfaction that apply not just to wordless documentation, but to other consumer products.

Norris Bradford, Annette. STC Proceedings (2004). Articles>Documentation>Technical Illustration>User Experience

Customer Support on the Web

Customers avoid web-based customer support if information is not relevant, out of date or hard to find. Without a business commitment to addressing these issues, customers will continue to prefer contacting a service representative by phone.

Szuc, Daniel and Gerry Gaffney. Apogee (2005). Articles>Documentation>Help>Online

Customized Book-Based Electronic Collections: Case Study and Exploration of Issues  

Collections of technical documentation vary in their delivery media, file format, user interface and degree of integration of the component documents or information. This paper looks at definitions and attributes of collections before reviewing the development of book- based, customized CD collections in a company operating in a fast-changing industry. Issues arising from this case study are explored and findings are used to identify a broad categorization of collections and build a starting point check list for collection design. Major issues in collection building are summarized.

Symonds, Yosef. STC Proceedings (2004). Articles>Documentation>Online>Case Studies

Customizing the Appearance of Your Manual, Help System, and HTML Help System  

Doc-To-Help gives Help authors complete control over the look, feel, and content of a project's printed manual, Windows Help system, HTML files, and HTML Help system. Maintaining different content is controlled using Doc-To-Help's conditional text feature, which allows authors to mark content for print-only, online-only, WinHelp-only, and so on. In this article we discuss how you control the appearance of the printed manuals and Help using Word templates, and HTML output using cascading style.

ComponentOne (1999). Articles>Content Management>Single Sourcing>Documentation

Darwin Information Typing Architecture (DITA)  

The purpose of this research note is to introduce the Darwin Information Typing Architecture (DITA) and highlight its relationship to other information architectures like DocBook and Information Mapping.

Namahn (2005). Articles>Documentation>XML>DITA

The Darwin Information Typing Architecture (DITA): Applications for Globalization    

Translation of documentation has traditionally been a major expense in the globalization process, especially if translations are required for multiple languages. The Darwin Information Typing Architecture (DITA) is an XML-based architecture for creating topic-based and information-typed content. It provides a number of features that, in addition to supporting high-quality information delivery, allows for more efficient and reliable localization of information. This article provides both an introduction to DITA and a discussion of DITA features that enhance document globalization.

Harrison, Nancy. IEEE PCS (2005). Articles>Documentation>Localization>DITA

Dealing With an IT Scourge: Process Documentation  

In this article, we outline how IT analysts can effectively make determinations about the value of process documentation, and in the process, transform a potential scourge into a possible blessing.

Schiesser, Rich. TechRepublic (2005). Articles>Documentation>Programming>Project Management

The Death of Paper Manuals

I'll pay $20 for a manual. I'd even pay $30-40 for a manual (grudgingly...). But $65 for a manual that should be in the damn box to begin with? Sorry... NO.

DealMac (2003). Articles>Documentation>Online>Help

Declarative Information in Software Manuals: What's the Use?    

Declarative information is often considered to be of little value to software manual users, for two reasons: some research results state that it is consistently skipped by users, and other research results show that declarative information does not enhance task performance. This study puts these conclusions to the test, because the research underlying them does not support such general conclusions. Two experiments are conducted to collect quantitative data about the selection and use of procedural and declarative information and to investigate whether or not the use of declarative information affects task performance and knowledge. A new technique for measuring information selection was developed for this purpose: the click and read method.

Ummelen, Nicole. ACM SIGDOC (2000). Articles>Documentation>Rhetoric

Defining Information Architecture Deliverables

One of the hottest topics these days in Information Architecture circles is documentation. This is probably partly because the IA's role is so ill defined. Our jobs sit perched between engineering and graphic design: go too far in one direction, we're doing the coding, go to far in the other and we are doing the design. Neither role maximizes the architect's key skills; defining the organizational structure and behavior of the web site or application. An IA is most effective when they leave implementation and final graphic design out of the mix. The documents they create to express this have to be crafted with equal skill and diplomacy.

Wodtke, Christina. SitePoint (2001). Articles>Information Design>Documentation

Delivering Documentation on CD-ROM and the Internet  

Many companies produce products on the cutting edge of technology but still publish documentation using old technology. At N.E.T., we develop our information with the goal of using the latest technologies; this includes using the Internet and CDROM as our primary modes of delivery.

Jones, Margaret and Pat Adams. STC Proceedings (1998). Articles>Documentation>Online

Delivering Training and Support Using Windows Help  

The Windows Help utility is familiar as a tool to provide context-sensitive and procedural help for people using a software application, but it also a highly effective tool for providing many kinds of desktop-based training and support within an organization. During this session, we look at a variety of systems built using Windows Help and explore why this was a good choice for the particular project.

Deaton, Mary M. STC Proceedings (1997). Articles>Documentation>Online>Help

Der Weg zum absoluten PDF-Standard in der Technischen Dokumentation

Kein Wunder müssen Technischen Redakteure die ganze Zeit Druckdaten aufbereiten, wenn jede Druckerei ein anderes Datenformat verlangt. Eine Lösung musste her. Ein Standard. Und so ist auch PDF/X-3 ein Thema in der Technischen Dokumentation.

TECOM (2003). (German) Articles>Documentation>Software>Adobe Acrobat

Design Checklists for Online Help

Online help systems have evolved over the past 20 years to meet the needs of our users. Designers must consider the content, format, presentation, navigation, and access methods of online help systems. A series of design checklists based on the past 20 years of research are presented in this paper, which summarizes a journal article currently being considered for publication. The latest trend in online help system design is embedded user assistance, which includes integrating information into the interface and including an embedded help pane within that interface to display a context-sensitive online help system.

Corbin Nichols, Michelle. WritersUA (2004). Articles>Documentation>Help>Online

Designing a Product Documentation Library for the World Wide Web  

Designing a documentation library for the WWW requires understanding the unique capabilities of the Web and how they can be used to meet the documentation needs of customers. The Web is ideal for distributing information and interacting with customers, but certain considerations apply. Will you offer free Web access to manuals you normally sell? If you choose to limit library access to customers, how will you prevent unauthorized browsing? Do you want to use the Web to solicit readers’ comments? With the Web, you can effortlessly distribute new versions of documentation, but you must carefully identify each version to avoid customer support problems.

Bassow, Fern and Holly Gross. STC Proceedings (1996). Articles>Documentation>Online