Introduction
What I am not going to do
-
Show you how to write--you learn by doing
-
Hire an editor, take a class, attend a hands-on seminar
-
Join the Society for Technical Communication (STC) and attend meetings and conferences
-
-
Take self-paced tutorials
-
Read good writing--if you train your ear you'll know when your writing sounds good
-
Show you how to save time
It takes longer to write shorter. But you can save a lot of other people a lot of time:
-
Expert reviewers
-
Editors
-
Others who are duplicating your efforts
-
Your users!
What I am going to do
-
Define some of the simplified language movements
-
Explain in seven steps how to trim your documentation
-
Point you to some good sources
-
Pontificate (if I can work it in)
What I hope you'll do
-
Give me your feedback
-
Share any tips
-
Recommend other sources
-
Share stories from the trenches
What
minimalist writing is
(And what this presentation isn't)
Minimalist writing is a phrase used by John M. Carroll in his famous book,
The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill
John M. Carroll:
-
Has a PH.D in experimental Psychology from Columbia University
-
Is the head of the Center of Human-Computer Interaction at Virginia Tech
-
Researches how people learn software application skills
Minimalists are fond of the word heuristics:
--A speculative formulation used as a guide in investigation or problem solving.
--Educational method in which learning takes place through discoveries made by the student.
The American Heritage Dictionary
The gist of it:
-
Carroll thinks documentation uses a "systems" approach, that impedes learners
-
The system approach defines the flow of tasks that are taught and drilled
-
The structure is too rigid and can conflict with learning styles, because "many learners do not follow instructions willingly or well"
-
He says the most efficient way to learn tasks is to do them, not read about them
-
Learning a tool is a means to an end, not the end itself
Principles
-
Get learners doing real work ASAP
-
Minimize overview--provide only what is needed to learn the task, and maybe put it last
-
Set up an environment for trial-and-error exploratory learning
-
Provide good error recovery information
-
Procedures should be modular, and usable in any order
Other writing isims
There are other approaches to writing documentation that is clear, concise, and user friendly.
Plain English, Plain Language
-
A crusade for clear, concise, and well-organized documentation
-
Especially active in the government sectors
-
Joseph Kimble, a law professor at Thomas Cooley Law School, is a well-known advocate for using plain language in legal documents
-
Read more about it in the STC Technical Communication journal Volume 48, Number 3
Simplified English
The European Association of Aerospace Industries (AECMA) developed guidelines for writing aircraft maintenance documentation. Features:
-
Simple syntax
-
A limited number of words (lists are provided)
-
A limited number of meanings for the words--usually each word has one meaning
-
A limited number of parts of speech for the words--usually each word has only one part of speech
Controlled Language
-
Designed to make translation faster and more accurate
- Uses one set of terms for a technology
