http://tc.eserver.org/dir/Articles/Writing/Minimalism A listing of the most recently indexed works about Articles and Writing and Minimalism in the field of technical communication (and technical writing). en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Articles/Writing/Minimalism http://tc.eserver.org/35714.html http://tc.eserver.org/35714.html The point of a quick-start guide is, as the name says, to help the users get on their feet as fast as possible. This requires the writer to ask, “What is the absolute minimum that someone needs in order to get started?” The next best question is “What is the user going to do the most often?” http://tc.eserver.org/35634.html http://tc.eserver.org/35634.html The procedure I wrote about creating a Twitter list uses abbreviated content. This post describes the reasoning behind and decisions made in writing the topic. http://tc.eserver.org/35535.html http://tc.eserver.org/35535.html Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation. http://tc.eserver.org/35219.html http://tc.eserver.org/35219.html In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses. http://tc.eserver.org/35125.html http://tc.eserver.org/35125.html I’m advocating boiling the documentation down to the essentials. Remove any superfluous material. Tell the user how to do things with a piece of software or a gadget, not what that something can do. You might wind up with documentation that’s just a set of procedures connected together by linking material and cross references. Don’t bog them down with what’s not necessary for them to get things done in a fast and efficient way. http://tc.eserver.org/35090.html http://tc.eserver.org/35090.html Be vicious when you edit. Vicious. Follow these recommendations with zealous fervor. They help your writing say what it should in a way we’ll understand. http://tc.eserver.org/35026.html http://tc.eserver.org/35026.html The health care reform bill now under consideration in the House of Representatives includes a proposal that certain disclosures in insurance policies be made in “plain language.” Another piece of legislation now being considered by both houses of Congress would likewise require uniform and simplified coverage information, much like what’s required on nutritional labels. These are excellent proposals, but they do not go far enough. Plain-language disclosures of some policy information and consumer-friendly labels are no substitutes for making an entire policy readable. http://tc.eserver.org/35024.html http://tc.eserver.org/35024.html Minimalism is something people might strive for, but they don’t know where to start. http://tc.eserver.org/34978.html http://tc.eserver.org/34978.html Writing tightly means packing the most information into the least amount of space. It's not easy, but when you do it, the result is like magic. The key to being an effective writer is to keep what you’re writing short, to the point, and easy to read. Like the best writing on the Web. http://tc.eserver.org/34804.html http://tc.eserver.org/34804.html Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium. http://tc.eserver.org/34130.html http://tc.eserver.org/34130.html With the passing of the Brayley Bill in Congress, the significance of plain language has become even more apparent to technical communicators. The author lays out a step-by-step plan to maintain the relevance of plain language as an important and necessary profession. http://tc.eserver.org/33961.html http://tc.eserver.org/33961.html When you’re writing for the web, try to keep your sentences under 20 words in length. Your content will be easier to read this way. This is because it’s easier to read a few short sentences than it is to read one big one. http://tc.eserver.org/33329.html http://tc.eserver.org/33329.html According to Plain English Campaign (www.plainenglish.co.uk), plain English is "… something that the intended audience can read, understand and act upon the first time they read it. Plain English takes into account design and layout as well as language." Many organisations have found that plain English brings commercial advantages. http://tc.eserver.org/33333.html http://tc.eserver.org/33333.html Plain English is good for increasing the quality of written documents. Unfortunately, it has limits in many technical situations. We need a special form of language, known as a controlled language, to overcome those limits. One particular controlled language is ASD Simplified Technical English. http://tc.eserver.org/32097.html http://tc.eserver.org/32097.html A masterpiece of concision so tightly written that you almost don't need to read past the table of contents. http://tc.eserver.org/31672.html http://tc.eserver.org/31672.html More importantly, most lists of ten principles of clear writing are not really principles at all, but rather tips and technique. Understanding why you are doing something, i.e., the benefit you will gain, helps ensure that you will actually do it and do it consistently. Too often, when we are told only what to do, we follow the instruction half-heartedly, inconsistently, or not at all. http://tc.eserver.org/31609.html http://tc.eserver.org/31609.html Writers are great inflators. We can take a simple half page describing a computer interface and in a few hours transform it into a 35-page document complete with glossaries, type conventions, overviews, introductions, mission statements, charts, clip art, and copyright pages full of disclaimers, trademark acknowledgements, and credits. The results will make the people in marketing and sales simply glow. http://tc.eserver.org/31607.html http://tc.eserver.org/31607.html Effective writing does not come by chance. The creation of all documents, including forms, labels, websites, business letters, legal notices, manuals, procedures, reports, and proposals, usually involves the following key steps. http://tc.eserver.org/31610.html http://tc.eserver.org/31610.html If thought corrupts language, language can also corrupt thought. A bad usage can spread by tradition and imitation, even among people who should and do know better. http://tc.eserver.org/31612.html http://tc.eserver.org/31612.html Call it the benefits of plain language. The literature contains studies about these benefits, but no one has ever collected and summarized the studies in a way that makes their full force apparent. As you read the summaries in this article, try to imagine the costs of poor writing — typified by officialese and legalese — in business, government, and law. The costs are almost beyond imagining, and certainly beyond calculating. If this evidence doesn't convince organizations and individual writers that plain language can change their fortunes, probably nothing will. http://tc.eserver.org/30788.html http://tc.eserver.org/30788.html ASD-STE100 Simplified Technical English (formerly AECMA Simplified English) is a specification for writing aircraft documentation. The principles can be applied to all industry sectors. ASD-STE100 provides a set of writing rules and a dictionary of words and their meanings. It has a limited number of words; a limited number of clearly defined meanings for each word; a limited number of parts of speech for each word; a set of rules for writing text. This article outlines the standard, and shows how it helps to prevent ambiguity in text. http://tc.eserver.org/30734.html http://tc.eserver.org/30734.html Find the one thing you want people to remember as you write a posting for a Web page, a subject line for an e-mail or a headline for a newsletter. http://tc.eserver.org/30600.html http://tc.eserver.org/30600.html During this workshop, To Be or Not To Be, the workshop presenters demonstrate how getting rid of the verb 'to be' increases accuracy, clarity and effectiveness in verbal communication. E-Prime originated in the field of general semantics; it consists of the English language, but excludes all forms of the verb 'to be.' Practitioners in the field of general semantics have developed a number of techniques that promote clear understanding of communication in the world around us. The workshop presenters strive to create an environment for participants to learn the philosophical background and practical application of the English language subset known as E-Prime. http://tc.eserver.org/30561.html http://tc.eserver.org/30561.html 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. http://tc.eserver.org/30362.html http://tc.eserver.org/30362.html Try to rid your writing, especially business writing, of unnecessary words. They take up space, look impressive only to naive readers, and say nothing. http://tc.eserver.org/30200.html http://tc.eserver.org/30200.html Plain language is clear, concise, and straightforward presentation of information. It is professional content structured to eliminate ambiguity and confusion in technical, government, and legal documents. Plain language allows readers to fully comprehend complex regulations, practices and instructions by requiring the language of bureaucracy to reflect the language of everyday speech. http://tc.eserver.org/29888.html http://tc.eserver.org/29888.html 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. http://tc.eserver.org/29396.html http://tc.eserver.org/29396.html 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. http://tc.eserver.org/28008.html http://tc.eserver.org/28008.html In web design screeds, the most commonly cited book is not what you might expect. It is not by Jakob Nielsen or Jeffrey Zeldman or Edward Tufte. It's not even on design or typography or code. It is a thin volume of guidelines on writing by a professor 'at the closing of the first world war' and treasured by one student enough to put it into print. William Strunk was the professor, and E.B. White, author of Charlotte's Web, was that grateful student. White took the master's set of laws, removed some 'bewhiskered entries,' corrected some errors, and added his own chapter at the end for 'those who feel English prose composition is not only a necessary skill but a sensible pursuit as well.' http://tc.eserver.org/27986.html http://tc.eserver.org/27986.html Proposes that STC become involved in brainstorming ideas about Simplified Technical English, thus leading the way for clear, correct documentation. http://tc.eserver.org/27754.html http://tc.eserver.org/27754.html For a profession full of sharp people, software engineering produces some hideous prose. How many times have you tried to read a technical document and failed because it was, in a very real sense, unreadable? It doesn't have to be this way. We technical types can improve our writing simply by applying some of those hard won coding skills to to those other, human, languages. I may be grammar challenged and spelling incapable, but writing code has taught me a few things about writing for people. http://tc.eserver.org/27733.html http://tc.eserver.org/27733.html A lot of the time, management-speak simply seems ridiculous. But campaigners for plain English say there is a more serious side to the issue. http://tc.eserver.org/27739.html http://tc.eserver.org/27739.html Over the last two decades, a ‘culture of clarity’ has been gaining ground in many large organisations around the English-speaking world. In the United Kingdom, government departments, banks, insurance companies, local councils and others have come to realise that clear communication is actually a good idea. Instead of writing to impress or confuse, they are now writing to inform and explain. They are using plain English to do this. http://tc.eserver.org/27488.html http://tc.eserver.org/27488.html 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.) http://tc.eserver.org/25992.html http://tc.eserver.org/25992.html Occasionally, when you try to convert from legalese to plain language, someone will come forward and assert that you made a mistake. You missed something in the translation. You inadvertently changed the substance. http://tc.eserver.org/25990.html http://tc.eserver.org/25990.html 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. http://tc.eserver.org/25991.html http://tc.eserver.org/25991.html Awareness of the need for clear language isn't new in the US government. http://tc.eserver.org/25996.html http://tc.eserver.org/25996.html Looks at a number of institutions that are finding ways to insert plain English into communication between scientists and the public, as well as among scientists of different disciplines. http://tc.eserver.org/25997.html http://tc.eserver.org/25997.html This article outlines the benefits you can realize by articulating your science clearly and succinctly; next time, we'll look at how and why several academic and government institutions as well as some publications are encouraging this trend. http://tc.eserver.org/26002.html http://tc.eserver.org/26002.html The traditional way of writing government documents has not worked well. Too often, complicated and jargon filled documents have resulted in frustration, lawsuits, and a lack of trust between citizens and their government. To overcome this legacy, we have a great responsibility to communicate clearly. http://tc.eserver.org/25126.html http://tc.eserver.org/25126.html Minimalism is more a methodology or set of principles than a set of measurable qualities. In order for your writers to move to a minimalist approach to documentation, you must be able to explain what you mean by the term and what you expect from your writers. http://tc.eserver.org/25004.html http://tc.eserver.org/25004.html George Orwell once wrote that `[g]ood prose is like a window pane.' What I take Orwell to have meant by that remark is that when people read good prose, it makes them feel as if they've `seen' something more clearly. http://tc.eserver.org/24890.html http://tc.eserver.org/24890.html 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. http://tc.eserver.org/24120.html http://tc.eserver.org/24120.html 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. http://tc.eserver.org/24090.html http://tc.eserver.org/24090.html 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. http://tc.eserver.org/23941.html http://tc.eserver.org/23941.html Make your documents easy for EFL users to read and understand, and communicate successfully with people all over the world. About one billion people use English as a foreign language (EFL). You can avoid most pitfalls of cross-cultural communication by using global English. http://tc.eserver.org/23903.html http://tc.eserver.org/23903.html Plain language has to do with clear and effective communication -- nothing more or less. It does, though, signify a new attitude and a fundamental change from past practices. http://tc.eserver.org/23917.html http://tc.eserver.org/23917.html The phrase 'Plain English' (although widely used) is a little misleading. It is nothing to do with the English language as such. The principles outlined here apply to writing in any language. A more accurate expression is 'plain language'. http://tc.eserver.org/23916.html http://tc.eserver.org/23916.html When you reach out to your readers, you show that you have considered who they are and what they need to know. Communicate a concern for your readers' needs so they will be receptive to your message. http://tc.eserver.org/23756.html http://tc.eserver.org/23756.html Last month I stated this is not a place for jargon. I felt that was important enough to call out. I certainly am being called to task for that. http://tc.eserver.org/23672.html http://tc.eserver.org/23672.html Some quick tips toward a clearer, more lucid, meaningful,…well, you know what I mean. http://tc.eserver.org/21682.html http://tc.eserver.org/21682.html 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. http://tc.eserver.org/21517.html http://tc.eserver.org/21517.html When creating online and hardcopy information for software, technical writers tend to be prolific. Every piece of information is important, isn't it? And more information means happier users, right? Not every piece of information is necessary, however, and users don't want more information. Instead, they want the right information with easy access to it. This panel discussion describes why you, as a technical writer, need to reduce information and how you can reduce it by incorporating the following techniques and activities into the writing process. http://tc.eserver.org/21389.html http://tc.eserver.org/21389.html 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. http://tc.eserver.org/20916.html http://tc.eserver.org/20916.html If you want to test the clearness of your writing, you may wish to consider using a 'fog index.' Fog indexes measure the complexity of writing samples, and often provide a means of calculating the reading or educational level required to understand a particular passage. Some fog indexes are available as computer software programs, or you may do the calculations yourself. http://tc.eserver.org/19839.html http://tc.eserver.org/19839.html People use documentation differently from what we might expect. They don’t like to read; instead they jump to a task with prior knowledge, and sometimes don’t realize they’ve made an error. Understanding how users learn and applying John Carroll’s minimalist principles will help provide solutions to this problem. Documentation that has been successfully planned and designed for minimalism may take longer to create than other manuals, but reaps the benefits of making users more productive and happy, while reducing support calls, maintenance, translation, and publishing costs. The key factors to a successful minimalist approach (or any good documentation design) are a keen understanding of your users, prototypes designed to match tasks relevant to users, and iterative testing to improve each draft. http://tc.eserver.org/19731.html http://tc.eserver.org/19731.html 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. http://tc.eserver.org/19703.html http://tc.eserver.org/19703.html Perhaps the worst way to condense a book is by using smaller or condensed type; you want to be especially careful that all fonts are legible. Neither should you save space by tossing out pictures or diagrams that clarify subjects. Some engineers cram paragraphs together, but paragraphs are valuable structural devices that can make subjects more clear. So the clue to successful condensation of text is not mechanical miniaturization but literary efficiency. http://tc.eserver.org/19587.html http://tc.eserver.org/19587.html Peter Zvalo looks at the plain language movement, its promoters and its critics. http://tc.eserver.org/19052.html http://tc.eserver.org/19052.html In an effort to reduce phone calls and improve customer service, the Washington State Department of Labor and Industries(L&I), in July 2001, launched 'Plain Talk' – a year-long project to rewrite 100 bureaucratic form letters into plain English. Hundreds of thousands of form letters are used each year by L&I to process claims, to issue workplace safety and health citations, and to handle many other workplace issues. As the Plain Talk project manager, I decided to focus on the department’s highest-frequency form letters and now work with 12 programs to rewrite them into clear and simple language. The effort is backed by a strong message from the governor and agency director, high-quality training, ongoing mentoring, and “reality check” usability testing. The project is due to be completed by the end of June 2002.