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 Hack (A Technical Writer's Journal): From Acrobat to FrameMaker

FrameMaker is the industry standard for writing book-length documents. It is a powerful program capable of creating books of well over a thousand pages. The learning curve for the program is significant. FrameMaker is a much different animal than Microsoft Word and other word processors.

Hewitt, John. Writer's Resource Center (2004). Articles>Document Design>Software>Adobe FrameMaker

Document Hack (A Technical Writer's Journal): The Acrobat and the Illustrator

Using Acrobat, you can make minor edits to a PDF file, but Acrobat documents are very sensitive. Typing a single character can throw several lines off, destroy tables and cause all sort of other troubles. Alternately, it can be relatively uneventful and painless. You will not know until you type in that character.

Hewitt, John. Writer's Resource Center (2004). Articles>Document Design>Software>Adobe Acrobat

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

The Effects of Using Colored Paper to Boost Response-Rates to Surveys and Questionnaires    

Many people have speculated over the last 80 years or so about the possibilities of using colored paper to boost response-rates to surveys and questionnaires, and several studies have been carried out. Most of these enquiries report no significant effects from using colored paper, although there have been some exceptions. In this investigation we pooled together the results from all of the experimental studies known to us on the topic and we carried out a meta-analysis to see if there might be a positive effect for colored paper overall. The results indicated that this was not the case, for we found no significant differences between the response rates to white and to colored paper in general. However, when we considered separately the most common colors used, it appeared that pink paper had the greatest effect. "One of the first considerations [to obtain a high response-rate] is the color of paper used in mail questionnaires. United States government officials who are responsible for the mailing of several million questionnaires every year have definitely determined that yellow paper gives the highest percentage of returns, with pink next in effectiveness, while all dark colors give much smaller returns" [1, p. 142].

Hartley, James and Andrew Rutherford. Journal of Technical Writing and Communication (2003). Articles>Document Design>User Centered Design>Color

Efficiency: It's Not Just for Production Monkeys

With a few free tools from software companies and other users, you can carve out more time for what you really love -- creativity.

Ashcroft, Sean. Creative Pro (2007). Articles>Document Design>Software>Adobe InDesign

Embedded Indexing in FrameMaker   

Embedded indexing is the process of creating index entries electronically in a document’s files. Although desktop publishing packages are not the best tools for indexing, they can be used to create effective embedded indexes. For technical documents that will be updated frequently or will go online, technical communicators can create embedded indexes that will help their audience find information quickly and efficiently.

Mauer, Peg. STC Proceedings (1999). Articles>Document Design>Indexing>Adobe FrameMaker

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

The Empowered User: A New Approach To Software Documentation  

User empowerment offers a strategy for addressing the software end user's needs. The definition of user empowerment emphasizes a user-driven, informationmanagement oriented approach in response to changes that have taken place in the modern workplace after computers and computer software arrived. Working with software requires a significant shift in thinking and learning, responding to increased abstraction, isolation, and information volumes. Computermediated work demands that users develop new skills and job roles, and that documentation writers develop new techniques for manuals.

Barker, Thomas. STC Proceedings (1994). Articles>Documentation>User Centered Design

Enhancing Customer Satisfaction by Assuring Documentation Quality  

From the customer's perspective, an important and visible part of a product or service is its documentation. Bellcore's Technical Publications (Tech Pubs) organization uses a Quality Assurance (QA) program that focuses on enhancing customer satisfaction through delivering high-quality documentation. This program emphasizes a 'network' approach to documentation development, whereby technical writers can most efficiently use the support network of QA reviewers and management available to them. The Tech Pubs QA program draws on the needs of clients and the expertise of technical writers to strive to achieve the highest level of quality possible in producing documentation.

Dolese, Cathy and Tara Durkin. STC Proceedings (1993). Articles>Documentation>Quality>User Centered Design

Enterprise Agility: SOX and Enterprise Information Integration  

The intent of Sarbanes-Oxley (SOX) can be characterized as risk reduction: reduce errors, inhibit fraud, and provide shareholders with transparent equal-access to material knowledge. But implementation is principally procedural controls and documentation, under threat of penalty. The vague parts of SOX are where the real leverage lies: principles of intent, and corporate transparency.

Dove, Rick. Paradigm Shift International (2005). Articles>Knowledge Management>Information Design>Documentation

Equations

Equations must have a number in parentheses at the right of the page. Must be numbered in the order they appear. Must be able to be read as part of the text.

Young, V.L. and K.J. Sampson. Ohio University (2004). Articles>Document Design>Technical Writing>Mathematics

An Evaluation of the Effectiveness of Automated Templates  

Automated templates are an alternative to traditional supporting information for helping users perform complex tasks. In this study users performed tasks with and without wizard to trial and error, printed manuals, and online the use of automated templates. Results suggest that if fakes help, and examined the use of supporting information some time for users to learn to use automated templates, but in performing complex tasks. We also considered once they do, the templates help users perform tasks more whether automated templates serve an educational successfully and more quickly.

Bayer, Nancy L., R. Darren Carleton, Susan Goetchus, Robert Krull and Rick S. Sapir. STC Proceedings (1994). Articles>Document Design>Content Management

Example Elaboration as a Neglected Instructional Strategy  

Summarizes psychological research on why some people learn better from examples than others do, and applies the results to improve software documentation and literacy outreach projects.

Girill, T.R. STC East Bay (2001). Articles>Documentation>Design

Explicit Structure in Print and On-Screen Documents    

The structure of print and on-screen documents is made explicit through headings and links. Three important concepts for understanding explicit structure are (1) the display-unit properties of each document medium, (2) the flexible relationship between explicit and implicit structure, and (3) the distinction between populated and unpopulated locations in a hierarchy. These concepts help us better understand standard print documents, structured writing, websites, help systems, and PowerPoint, as well as the potential effects of content management systems on how documents are created.

Farkas, David K. Technical Communication Quarterly (2005). Articles>Document Design>Information Design>Typography

Extracting Content

How to extract content from a portion of a PDF document.

Baker, Donna L. PlanetPDF (2004). Articles>Content Management>Document Design>Adobe Acrobat

Figuring Out What Your Customers Really Need  

Effective technical manuals and training meet the needs of the customer. No one will argue with that statement. But the trick is to identify the needs of the customer. This paper describes one method to focus product information development on the customer: the needs analysis survey. This methodology that is common in course development and training identifies the tasks customers perform. It also allows course developers and technical communicators to collaborate on an area that they both understand.

Brockett, Susan H. and Susan Katz. STC Proceedings (1996). Articles>Documentation>User Centered Design

First Contact: Talking to Your Documentation Users  

You've never met them before. To you, they may represent the unknown and the strange. They view things differently, and their ways may seem almost alien. Yet you are supposed to serve their needs. They are your customers. Isn't it time you made first contact? In this paper, we share lessons learned and invite you to being your own voyage of discovery.

Macdonald, Kyla and Judith Rachel. STC Proceedings (1998). Articles>Documentation>User Centered Design

Format Text with Style Sheets  

Format text once and apply the same style repeatedly and with ease. Style sheets in Adobe® InDesign® CS are a shortcut to formatting text.

Adobe. Articles>Document Design>Style Sheets>Adobe InDesign

FrameMaker Batch Processing and Automation Using MIF

Have you ever wanted to check a large set of FrameMaker files to make sure all the borders, text- symbols, and rulers are turned off? What about hyperlinks? Wouldn't it be nice to be able to automatically validate all the hypertext links within a large set of FrameMaker files? Did you ever wish there was a way to automatically convert a set of data into FrameMaker tables? You can do all these things, and more, using the Maker Interchange Format (MIF). This article presents some of the main features of MIF and gives an overview of some of the ways you can make use of MIF. Additional articles will delve deeper into using Perl to process MIF, providing details on specific applications.

Larsen, Seraphim. Silicon Valley Connection (2002). Articles>Document Design>Software>Adobe FrameMaker