heathergprint | view source | edit
WhatMinimalism in the context of technical communication is a research-based theory of learning and instruction developed by John M. Carroll in the late 1980s at IBM's User Interface Institute and first published in Carrol's book The Nurnberg Funnel. The theory comprises the following simple principles:
Minimalist documentation is the practical application of this theory to the process of authoring technical documentation, with the goal of producing user guides that function according to minimalist theory. The Greywalker Method is one such practical application, which implements all of the preceding principles by using a specific methodology, organizational structure, and two other principles that are generally considered as part and parcel of "good technical writing", but which are often paid only lip service and are not clearly categorized with specific guidelines:
Guide contents |
Tips and details
Significant design elements of minimalist documentation
A variety of design elements are used to convert the foundational principles of the theory of minimalism into the practical application of that theory in technical documentation. The Greywalker Method expresses these foundational principles with the following specific techniques:
Anchor instruction in the job domain
- Every task topic is rooted in a domain-oriented task using a domain-oriented topic title. Not a single topic describes how to "define a widget" or "print a foo report" because that would be system jargon and instructions that teach the system instead of explaining how to achieve a business goal with the help of the system.
- The framework topics that organize and present the tasks likewise use the exact structure and topic titles as your model of the job domain (your domain-task analysis).
- Sub-tasks that are system-oriented (defining foos and defining bars) are buried as sub-sections within a topic whose subject focus (and title) are squarely domain-facing, such as "Researching customer buying habits".
- Standalone concept and reference topics that present supporting information for multiple tasks are located in some appendix-style structures at the end of the guide. So these topic titles, which are often system-oriented rather than domain-oriented (of necessity) are the last things that readers see when they're scanning a list of contents. Action-oriented, domain-oriented headings are front and center in the browsing path.
Less is more
- All topics start with a visually-defined summary block that provides an "executive summary" of the total subject content of the topic. Readers can quickly grasp the major elements of the subject and its relationship to other subjects, and they don't need to delve into the further detail that follows the executive summary unless they want more information.
- Procedural steps (both in the task workflow block and in explanation blocks) purposely omit all detail that should be intuitive or easily figured out with just a little exploration by the target audience of the procedure. By encouraging active exploration to figure out some details left unstated in the documentation, you stimulate reasoning and improvising, and even invoke the Zeigarnik effect, all of which promote learning and retention. When you prescribe a detailed set of traditional action-response steps, you put the reader in a passive state where they might achieve the desired result but will remember very few details and will have learned no adaptive strategies along the way.
- Conceptual and reference information that does not directly support the tasks in a guide are omitted entirely. "Nice to know" information just gets in the way of readers who are trying to get something done.
- Conceptual and reference information that can be learned outside of your documentation are omitted entirely. For example, why regurgitate database schema information in documentation format when most of the same information could be discerned by browsing the database tables using your database management tools?
Eliminate sequence
- Within a guide, all activity group topics and their component task topics are presented in alphabetical order. No sequenced workflow among major tasks is implied, stated, or expected at the table of contents level.
- Within a specific task topic:
- Procedures in task workflow blocks and explanation blocks use numbered sequencing only when necessary.
- There are no "prerequisite" or "before you begin" sections that precede a procedure list. This information is presented instead in a standalone troubleshooting block. Why? Most readers skip anything that looks like prereqs and go straight to the thing that looks like a procedure. Then they get stuck, of course, because they skipped right over those important prereqs. From their point of view, they have encountered "trouble", so they are going to look for "troubleshooting" headings, not "before you begin" headings.
- There are no final steps in a procedure that point you to the next procedure in sequence, nor any sections with titles like "Where do you go from here?" Why? Readers might already have a strong idea of what they want to do next. They're exploring and making their own mental model of how to get things done with the help of your product. If they're truly stumped for what to do next, they are effectively in an error situation. Readers will soon discover that activity workflow blocks are the place to look when they aren't sure what to do next (or what should have been done before).
Expect user error and provide recovery instructions
- Every task topic has a troubleshooting block. If that block is empty when you are done drafting a task topic, something is probably wrong. Is your application workflow and UI really that bulletproof and intuitive? Information that goes in this block:
- Common errors that you can expect a significant portion of your readers to stumble upon, and the recovery information for those errors (or a link to the recovery information down in the detail block or perhaps in a [[[reference topic or another task topic.
- Links to prerequisite tasks or requirements. "Why didn't this work? Oh, I never defined that foo that is needed for this task, and I don't seem to have that system permission."
- Links to follow-up tasks. "Hmm, what should I do now? Oh, here's a suggestion to look at these other tasks next."
Information typing and minimalism
Traditional conventions of information typing are mostly disregarded in any minimalist documentation, not just in the Greywalker Method. Any semantic block might contain mixed information types. For example, a task workflow block might have some short, key concepts and facts intermingled directly in the procedural steps. Why?
- In some cases this provides for useful error detection and recovery (or prevention) within the context of the procedure itself.
- In most cases, however, this supports reader reasoning and improvising, which as John Carroll puts it in The Nurnberg Funnel: "Allowing learners in part to create, and not merely consume, instructional material, can enhance cognitive processes in many ways. It is well known that actively generating elaborations for material being learned can make it more robust and accessible in memory."
Some other nuances of this tight integration between procedures, concepts, and facts (aka "mixed topic typing") are:
- Overview blocks are omitted, because research shows that most readers actively skip any section labeled Overview, About, etc.
- Prereq blocks are omitted, because research shows that most readers actively skip any section labeled Prerequisites, Before you begin, etc.
- Stem sentences that introduce step lists are omitted, because research shows that most readers actively skip the paragraph immediately preceding the first numbered step in a step list.
Has minimalist theory been sufficiently vetted?
The professional fields of technical communication and instructional design have traditionally been slow to transform new theory into practical application. At the time this guide was written, it has been 20 years since Carroll first published his theory in The Nurnberg Funnel. By this point in time, the term "minimalism" has become a new, trendy buzzword in the technical writing community, although in this author's experience not many technical writers can accurately define the key elements of the theory nor describe successful design elements of the practical application of that theory.
Even the Wikipedia entry on minimalism at the time this guide was written contained some significant inaccuracies and deficiencies, such as the false claim that the Darwin Information Typing Architecture (DITA) "β¦is built on Carroll's theories of Minimalism and Horn's theories of Information Mapping".
One major consulting and training resource for the field of technical communication (JoAnne Hackos' ComTech has begun delivering workshops on minimalist documentation
Distinguishing characteristics of the Greywalker Method
There is no single "correct" approach to authoring minimalist documentation, nor is there any single, consistent "look and feel" to minimalist documentation. Any information product that significantly employs design elements that apply the four major principles of minimalism is effectively a minimalist information product.
The Greywalker Method is unique in the field of minimalism for several reasons:
- It is a comprehensive methodology for authoring documentation in a manner that fully employs the four major principles of minimalism in a systematic and extensive manner.
- It is the first (and currently the only) publicly available methodology for minimalist authoring of any sort.
- It describes a very specific structural content and visual format, using a set of specific topic types that are comprised of specific combinations of a set of specific semantic block types. If you're familiar with XML jargon and concepts, the Greywalker method essentially comprises a very specific set of document types and content models for each.
- It adds two more important principles of minimalism that I feel John M. Carroll "should have" expressed, but did not.
Other information you might need
- Getting Started: Authoring minimalist authoring with the Greywalker Method
- Concept topics: Authoring minimalist documentation with the Greywalker Method
- Reference topics: Authoring minimalist documentation with the Greywalker Method
- Reference: Semantic block types and details
- Reference: Topic types and details