Accommodating Active Learners in Software Documentation Decisions  

Recent research focusing on a minimalist approach to computer software documentation has explored ways to design computer software tutorials and workbooks for users with an active learning style. The principles of minimalism and active learning styles, however, are less frequently applied to traditional reference manuals. This paper reviews several elements of minimalism and suggests ways to apply strategies for active learners to traditional reference manuals.

Smart, Karl L. STC Proceedings (1993). Articles>Documentation>Instructional Design>Software

Advantage of a Rainy Summer

This article deals, despite the title above, with aspects on handling and checking of technical documentation. I consider these aspects as part of the functionality of documentation besides more conventional functionality such as factual correctness, layout, combination of figures and text.

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

Analyzing Your Users and Needs Before Creating the Help Deliverables; Interview with Nicky Bleiel

In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users.

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

Applying the Sensation-Perception Continuum to User Documentation  

The sensation-perception continuum represents the interplay of sensation and perception in everything we think and do. Technical communicators must exploit this continuum by understanding and applying sensory filters and perceptual tendencies in the design and development of information. This paper discuss three sensory filters: thresholds, cocktail-party effect, and sensory adaptation; it discusses four perceptual tendencies: perceptual set, figure-ground relationships, laws of grouping, and goodness of figures.

Coe, Marlana A. STC Proceedings (1996). Articles>Documentation>User Centered Design

Applying Web 2.0 Technologies to Technical Documentation

This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0".

Pratt, Ellis. Cherryleaf (2006). Articles>Web Design>Documentation>Technical Writing

Are We Giving Readers What They Want, in the Way They Want and Need It?

With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past?

DMN Communications (2008). Articles>Documentation>Technical Writing>User Centered Design

Beyond Software Manuals and On-line Help: Interactive Help

Software user guides have traditionally provided assistance when the user requested help. Context-sensitivity enabled help systems to predict the most appropriate topic to present. For Windows applications, the move from Microsoft WinHelp to the new Microsoft HTML Help format allows user instructions to be presented in the same window as the application. This offers technical authors some extraordinary opportunities to provide intelligent, predictive, interactive help without the user having to request it. In this paper, we will explore one of the first such interactive help systems (for the Archivist e-mail archiving software), and see where the technology is moving.

Self, Tony. HyperWrite (2003). Articles>Documentation>Interaction Design>Help

Building the Treasure House: Creating Knowledge Bases on the World-Wide Web  

Web knowledge bases offer an excellent platform for delivering technical documentation and customer support information. They also represent an area of great opportunity for technical communicators to expand their skills, satisfy their customers, and create value for their employers or clients. This session explores the components of a web knowledge base and the tasks involved in planning and building one.

Massa, Jack A. STC Proceedings (1998). Articles>Documentation>Online>Web Design

A Case of Exhaustive Documentation: Re-centering System-oriented Organizations Around User Need    

Braun Corporation's home-grown documentation processes served the organization well for its first 50 years as it grew from a local to a nationally-competitive producer of mobility and accessibility products. Now poised to become a global leader in its field, this corporation found its efforts hampered by ineffective and outdated documentation practices, which were hurting the company's competitive advantage. This article describes Braun Corporation's curious mixture of global reach and local isolation. By bringing in a technical communicator with expertise in user-centered design, Braun has begun reforming its formerly exhaustive documentation and communication practices. While technical communicators have incorporated a variety of strategies to develop user-centered and task-based documentation, less attention has been placed on changing the cultures of these organizations. The case presented here represents a shift from establishing documentation procedures to critically assessing and reforming existing procedures for the global workplace, describing the shift from ineffective and exhaustive processes to effective processes with defined goals and measurable outcomes. The article concludes with an inventory for determining whether other organizations are over-documenting processes and products, and offers suggestions for creating better documentation procedures.

Salvo, Michael J., Meredith W. Zoetewey and Kate Agena. Technical Communication Online (2007). Articles>Documentation>Management>User Centered Design

Communicating Rapidly Changing Information  

When purchasing complex software products, users frequently receive large quantities of information; however, to use the product efficiently, they need a visually obvious starting point that helps them locate the specific information they need. With maintained With the quantity and diversity of information, customers need to be able to find the information they need without flipping through endless pages. In order to give the users a starting point in all of the printed and ASCII file information. we created a document entitled the Guide to products, users can use the features available with a new release most efficiently if they have an overview of the major changes to the product and to the information about the product. By using visual devices and creating an overview document. for each release, technical communicators can decrease their costs and increase users' productivity.

Bown, Jennifer and Connie M. Bibus. STC Proceedings (1993). Articles>Documentation>User Centered Design

Comparative User-Focused Evaluation of User Guides: A Case Study    

A comparative evaluation of two user guides,--the document traditionally used by a company and a model document designed on the basis of research results and recommendations,--was carried out using a number of complementary approaches focusing on the user. The quality and suitability of these documents for the target audience were assessed in terms of content, structure, presence of certain organizational devices (such as headings) and pictures included. The results revealed that the model document was more attractive, more efficient, and better adapted to users' needs, thanks to its modular organization (being structured according to "functions"), a large number of pictures, the presence of headings, and rationalization of the vocabulary used.

Ganier, Franck. Journal of Technical Writing and Communication (2007). Articles>Documentation>Assessment>User Centered Design

Constructing a One-Stop "Answer Station" Website for Software Users

The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete 'Answer Station' that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This article discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.

Bleiel, Nicoletta A. and Beth A. Williams. WritersUA (2004). Articles>Documentation>Web Design>Help

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

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

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

Designing for Interactivity: Role Models, Guides, and Coaches  

This paper presents three methods of user assistance: role models (simple demonstrations), guides (structured walk-throughs), and coaches (active assistants). After a brief introduction, potential uses, available development tools, and additional information sources are discussed for each method.

DeLoach, Scott. STC Proceedings (1998). Articles>Documentation>Help>Interaction Design

Do Users Use a User Guide?  

Technical writers make distinctions between the types of documents they create: user guides, reference manuals, tutorials. But do users really understand these document types? How do users look for different kinds of information--and how do we, as technical writers, make it clear to them what types of information are available? This paper presents results of usability evaluations of documentation for electronic design automation software, showing how a writing team tried to improve the categorization and presentation of document types.

Heninger, Barbara L. and Michael J. Miller. STC Proceedings (2004). Articles>Documentation>User Centered Design>Genre

Do Your Manuals Put Children in Danger? A Survey of Juvenile Products Consumers  

What can manufacturers do to improve the readability of manuals that accompany juvenile products?

Manual Labour (2003). Articles>Documentation>User Centered Design>Children

Document Design: A Brief Primer  

Today's documentation must be designed with information retrieval as its key objective. When information is organized and mapped into a consistent, logical structure that uses retrievability aids such as labels that facilitate scanning, blocks of information, advance organizers for the information, keywords, meaningful indexes, and a hierarchical organization, readers can quickly locate and use the information that they need.

Flanders, Melanie G. STC Proceedings (1997). Articles>Documentation>Document Design>User Centered Design

Document to the Question: Understanding What Users Ask and Where They Look for the Answers  

The user's idea of the problem is often very different than the help or program designer's. The online help topics often reflect the designer's viewpoint, not the user's.

STC India (2003). Articles>Documentation>User Centered Design>Help

Documenting in N-Dimensional Space

As technical communicators, we are being challenged with how to structure information in a multiple dimensional space made possible with Web technology.

Albing, Bill. KeyContent.org (2005). Articles>Documentation>Information Design

Documenting Networks

Documenting networks is playing less with words, and more with diagrams. It also requires an engineering mind, an ability to think out-of-box, and creative mind. Technical writers can rise to a new scale and expand their skill sets if they are able to document networks.

EDITsphere (2007). Articles>Documentation>Intranets>Graphic Design

Documenting Schemas  

The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. Thereal challengeistocreateschemasthat arereadablebothdirectlybylookingat their sourcecodeandbydocumentation extraction tools.

van der Vlist, Eric. O'Reilly and Associates (2001). Articles>Information Design>XML>Documentation

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

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