Adding Life to Your Documentation  

Suggests several techniques technical writers can use to enliven their writing and improve their documentation.

Potsus, Whitney Beth. Intercom (2003). Articles>Documentation>Writing>Technical Writing

Anything That Can Go Wrong: Lessons Learned from A Decade of Toolkit Documentation  

Writing software toolkit documentation for programmers is a special challenge and opportunity for technical writers. Compared with writing software documentation for lay users, toolkit documentation is more demanding and exacting. Checking facts and finding tiny errors is like riding a motorcycle through a swarm of gnats. However, for me at least, toolkit writing has opened doors to a larger role and greater input into product design. Engineers treat me like a peer and I get to see into their culture. I know my readers and salespeople need me.

van Oss, Joseph E. STC Proceedings (1999). Articles>Documentation>SDK>Technical Writing

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

Can a Manual Entertain?  

MacDonald analyzes the success of irreverent software manuals such as the 'For Dummies' and 'Complete Idiot's' series and suggests ways writers of traditional technical manuals can make their own work more enjoyable to read.

MacDonald, Matthew P. Intercom (2001). Articles>Documentation>Writing>Technical Writing

Converting to Information Mapping: A Case Study  

Cisco Systems, Inc., uses electronic media as the primary delivery means for customer documentation and training. Information Mapping® techniques are being developed as a methodology for creating and linking modules of customer information. After selecting the Information Mapping methodology, we found it necessary to customize it for our needs. To implement Information Mapping methodology, we defined a system architecture consisting of three main subsystems: a document management subsystem, an authoring environment, and a publishing or delivery subsystem, In parallel with the customization and development of a system architecture, several writers began to implement the Information Mapping techniques to provide content to be put into the system being developed.

Garrett, Aviva, Haggai Mark and Jan Johnston-Tyler. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing

Creating Professional Documentation with Linux Tools

While Linux lacks standard Windows tools such as FrameMaker, RoboHelp, and WebWorks Publisher, it's still a viable environment for technical writers. Linux users can take advantage of a number of documentation tools, including both free or open source software (FOSS) and proprietary software. All of them give technical writers the ability to author and publish professional documentation.

Nesbitt, Scott. Newsforge (2006). Articles>Documentation>Technical Writing>Linux

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

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

Designing and Writing to Reduce User Errors  

A vast majority of documents (I consider print and online as documentation) often works to define the optimized error-free method of performing a task and provides a user with a straightforward solution. However, the user expects documentation to help solve problems and address errors. Thus, attention must be paid to potential problems users can have and how to correct them. Errors have different causes; the information designer should understand the potential types of errors since properly addressing each type requires a different approach in the design and documentation.

Albers, Michael J. STC Proceedings (2003). Articles>Documentation>Writing>Technical Writing

Developing a Web-Based Tutorial in RoboHelp

The very first thing you should do in developing a tutorial is to be familiar enough with the subject matter that you can write the content.

School for Champions (2005). Articles>Documentation>Writing>Technical Writing

The Documentation Scene

Funny thing, documentation. Ought to be easy enough, surely? So why the disappointing results? What IS the elusive spark which distinguishes the professional author from others who put their hand to the pen (keyboard)?

Mobbs, John. ISTC (2002). Articles>Documentation>Writing>Technical Writing

Documentation Solutions for Complex Tools: Task-Based Design at the Cross Roads  

For most of the technical writing community, task-based documentation has become the panacea for presentation of end-product document (in any of its myriad forms including traditional linear manuals and online help). We believe, however, that applying this method to a complex tool, (for example, a software tool without a Graphical User Interface), challenges the task-based approach.

Swallow, Lisa and Matt Laney. STC Proceedings (2004). Articles>Documentation>Writing>Technical Writing

Downsizing Documentation: Meeting the Challenge  

The redesign of the Microsoft Windows operating system along with a shrinking page count and Help file-size allocation, presented Windows User Education with a unique opportunity. We not only redesigned our entire documentation model, we also changed and improved our authoring tools. And, along the way, we changed how we did our work.

Bloch, Peggy, Phyllis Levy, Kimberly A. Parris and Gayle Picken. STC Proceedings (1995). Articles>Documentation>Technical Writing>Minimalism

Early Involvement: Writing at Product Design Time  

Lead writing is a process that moves the information development cycle into the product development cycle. Writers and programmers work together from the beginning to produce both code design and supporting information. This process ensures that information developers can actively participate in design, and programmers can contribute to supporting documentation. Both groups gain an appreciation for each other's perspective, expertise, and skills, producing a more customer-oriented product.

Coppola, Carolyn M. STC Proceedings (1993). Articles>Documentation>Writing>Technical Writing

Editing Your Own Documentation  

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'

Docsymmetry (2003). Articles>Documentation>Editing>Technical Writing

Eleven Tips for Writing Incredibly Useful Procedures

Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.

HelpScribe (2008). Articles>Documentation>Policies and Procedures>Technical Writing

The Elves and the Shoemaker—We Don't Wear No Pointy Hats  

When technical communicators are part of a development team, we can do much more than write manuals. Our analysis and communications skills, user perspective can help launch a project team into productivity. We have a unique skill set which enhances the productivity and quality of the development process. By involving us early, we can assume technical communications tasks that developers otherwise perform. This exposure gives us a broader and deeper understanding of that which we communicate. Our involvement means better communication; with users and team members, and in deliverables and development processes.

Mazur, Sue and Jamie A. McCanless. STC Proceedings (1994). Articles>Documentation>Writing>Technical Writing

A Guide for Software Project Managers - Planning User Documentation

A Guide to the Project Management Body of Knowledge (PMBOK® Guide)–2000 Edition is the main sourcebook in the project management field. Whilst it covers Project Communications Management, it doesn't extend to user documentation. This article seeks to provide guidance for project managers as to how the user documentation process fits in with the overall project planning. It examines: the traditional way documentation is approached and how it impinges on project planning the effects of making changes to this traditional approach.

Johnston, Carol. Cherryleaf (2003). Articles>Documentation>Management>Technical Writing

Guidelines for Writing Technical Documentation for an International Audience  

A guide to help technical writers in all countries who have to write English-language technical documentation for products that will be sold worldwide.

tekom (2003). Articles>Documentation>International>Technical Writing

Hidden Factors of Documentation Quality -- Part 1

The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.

Sesnovich, Bruce A. Boston Broadside (1993). Articles>Documentation>Quality>Technical Writing

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.

TechScribe (2003). Articles>Documentation>Writing>Technical Writing

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

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

Improving the Usability of Programming Publications  

This paper summarizes the work of a study group on ways to improve the usability of publications that support programming products. Task orientation, an approach to providing, organizing, and packaging information, is covered, together with innovations to improve the usability of programming publications: ease-of-use education, measurement of user opinion, and incorporating usability into the publications development process.

Bethke, W.M., P.H. Dean, E. Ort Kaiser and F.H. Pessin. IBM Systems Journal (1981). Articles>Documentation>Writing>Technical Writing