Conciseness is Key to Good Technical Documentation

One of the most important and difficult parts of technical documentation concerns writing in a concise manner. Technical writing is different than writing fiction or magazine articles, where a mood may be set or--in some cases--where space must be filled. (People seldom buy thin books.)

Kurtus, Ron. School for Champions (2005). Articles>Document Design>Technical Writing>Minimalism

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

Deadwood Phrases

Deadwood phrases are found in all types of writing. In technical writing they are to be avoided at all costs as documentation needs to be crisp, concise and accurate.

Klariti. Articles>Writing>Technical Writing>Minimalism

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

Eliminating Unnecessary Words

Using an extended example, this article shows how it is possible to reduce the number of words in a text and at the same time increase readability.

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

Get Rid of the Babble

Try to rid your writing, especially business writing, of unnecessary words. They take up space, look impressive only to naive readers, and say nothing.

Leigh, Heather. Crazy for Words (2007). Articles>Writing>Technical Writing>Minimalism

High Tech Humor

The remarkable growth of the information technology industry has created a tremendous opportunity for people with skill putting words on paper. Technical writers, once a rare and highly skilled position, are now as common as fruit flies—though they take up a lot more space. Yet the pay is pretty good considering how little work they actually do, so young English-major weenies desperate for employment continue to swarm around IT companies, hoping for a bit of rotting fru—er, looking for a plum position.

PlainLanguage.gov (2005). Articles>Writing>Technical Writing>Minimalism

Needless to Say

The needless repetition of words and the repeating of ideas is everywhere - in newspapers, books, magazines, e-mails, television, and even in conversation. They’re called redundancies and the English language is full of them. In fact, research shows that about 50 percent of English is redundant.

Dowling, Dave. Indus (2003). Articles>Writing>Technical Writing>Minimalism

Reducing Complexity in Documentation  

With more emphasis being placed on customer satisfaction, technical writers need to focus on information strategies that will lead to happier customers. The complexity of the information is one common complaint of customers. Writers need to understand what customers think is complex. Then, writers need to develop strategies to combat these complexities.

Roscoe-Iverson, Ellen. STC Proceedings (1993). Articles>Documentation>Technical Writing>Minimalism

Simplified Technical English: STC Should Take the Lead  

Proposes that STC become involved in brainstorming ideas about Simplified Technical English, thus leading the way for clear, correct documentation.

Lester, Larry. Intercom (2006). Articles>Writing>Technical Writing>Minimalism

Style That Economizes Mental Energy  

Perhaps the most important feature of good writing style for scientific and technical communication is economy: writing that reduces the mental labor of the reader or user. I describe the principle of "conservation of mental energy" as developed by Herbert Spencer and extended by later studies in readability and psycholinguistics. Stylistic techniques that make reading easier have powerful application to the prose crafting that sci/tech communicators do every day. The idea of conserving mental energy, or being "efficient" in communication, gives us a touchstone for thinking about good style and a rationale for explaining why it's valuable.

Hirst, Russel. STC Proceedings (2004). Articles>Writing>Technical Writing>Minimalism

Review: The Nurnberg Funnel by John M. Carroll

In the Nurnberg Funnel: Designing Minimalist Instruction, John Carroll presents some helpful ideas based on some useful research on how the initial self-instruction (often called 'tutorials') should be developed and written.

Horn, Robert E. DITA Users (1999). Articles>Reviews>Technical Writing>Minimalism

The Zen of Minimalism: Designing a Top-of-Class Manual for Beginners and Advanced Users

Can using minimalist documentation improve accuracy and learning speed for beginners as well as for advanced users? I tested this question using Microsoft Access for Windows 95 ® and three different third-party manuals explaining this product. Then I set up three main tasks for the user in a usability test. For each task, I provided the task description in blue type, and then copied the appropriate documentation in black. Documentation for each of the three tasks was reprinted from a different book.

Stieren, Carl. Simware (1998). Articles>Documentation>Technical Writing>Minimalism