10 7 steps to minimalist writing - ocstc · 7 steps to minimalist writing 1. analyze the user’s...

1

10 7 steps to minimalist writing

STC Region 8 ConferenceNovember 2, 20001

Mary Ann [email protected] 2001

What I’m not going to do

Teach anyone how to write—you learn by doing

Hire an editor, take a class, attend a hands-on seminarFind out which local colleges are teaching what, when, and whereAttend STC seminars!Take self-paced tutorialsRead good writing—if you train your ear you’ll know when your writing sounds good

more… of what I’m not going to do

Show you how to save time

It takes longer to write shorterBut you can save a lot of other people a lot of time:- Expert reviewers- Editors- Others who are duplicating your efforts- Your users!

2

What I am going to do

Define some of the simplified language movementsExplain in seven steps how I cut my documentationPoint you to some good sourcesPontificate (if I can work it in)

What I hope you’ll do

Give me your feedbackShare any tipsRecommend other sourcesShare stories from the trenchesTell a joke

What minimalist writing is(Or what this presentation isn’t)

The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer SkillBy John M. Carroll- PH.D in experimental Psychology from Columbia University- Head of the Center of Human-Computer Interaction at

Virginia Tech- Researches how people learn software application skills

3

Minimalists are fond of the word heuristics

1. A speculative formulation used as a guide in investigation or problem solving.

2. 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 systems 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 ASAPMinimize overview—provide only what is needed to learn the task, and maybe put it lastSet up an environment for trial-and-error exploratory learningProvide good error recovery informationProcedures should be modular, and usable in any order

4

Other writing isims

Plain English, Plain Language

A crusade for clear, concise, and well-organized documentationEspecially active in the government sectorsJoseph Kimble, a law professor at Amherst College, is a well-known advocate for using plain language in legal documentsRead more about it in this quarter’s issue of STC Technical Communication (Volume 48, Number 3)

There are other approaches to writing documentationthat is clear, concise, and user friendly.

more… writing isims

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

Simplified English

The European Association of Aerospace Industries (AECMA) developed guidelines for writing aircraft maintenance documentation. Features:

more… writing isims

Controlled Language

Designed to make translation faster and more accurateUses one set of terms for a technology

5

7 Steps to Minimalist Writing

1. Analyze the user’s goals2. Design the document to support the user3. Write once and use many times4. Write transparently5. Edit 6. Test7. Rinse and repeat

Step 1

Analyze the user’s goals

Know your user

Know what they know alreadyKnow what he or she wants to do Know what they’ll need before they can start:- Knowledge- Setup

More… Step 1

Marketing should have answers.

But customer support will really know.

6

Step 2Design the information to support the user

Be consistent. Use:

The same types of informationIn the same orderIn the same style

more… Step 2

Use an architectural style guide. Define:

The types of information to includeWhere they goWhat order

more… Step 2

Write only the overviews the users really needLayer the information for different usersWrite procedures in task orderSet them up so they can stand on their ownIf there is more than one way to do it, explain only one way

7

Step 3

Write once and use many times

If you use the same information in many places, write it once and link.

Step 4

Write transparently

Write sentences that your reader can read once and understandKeep it simple Write as though you are talking to a friendTrim the fat…

more… Step 4Trim…

Use the active voice—find the true subject and the true verb

- The occurrence of the troubleshoot mode can be caused by several different problems.

- Different problems can start the troubleshoot mode.

8


Remove adjectives

- The results are applicable only to the final example.

- The results apply only to the final example.


Remove redundancies

- The basic fundamentals are simple.

- The fundamentals are simple.


Find one word

- In the unlikely possibility that…

- If…

9


Remove or rephrase prepositions and prepositional phrases

- You should free up the spindle before spinning.

- Free the spindle before spinning.


Use a prefix (but don’t make one up)

- If you don’t spell the word correctly…

- If you misspell the word…


Use a shorter word

- Oil the blunkard to facilitate removal.

- Oil the blunkard to ease removal.

10


Remove or rephrase adverbs

- Tighten the screw thoroughly.

- Tighten the screw.


Don’t use simply or utilize.

- Please don’t.

Do leave in the the’s and the a’s.

- Pull lever.

- Pull the lever.


Use flow charts

Draw the information and use callouts

11

Step 5

Edit

1. Edit2. Read it out loud and edit 3. Have someone else edit

- Say “thank you,” not “yeah but…”And make the changes.

more… Step 5

How to edit someone else’s work

Read it through once while you sit on your hands

(Get the information, purpose, and style of the document before you get out your pen.)

more… Step 5

Check:Is the information complete? (check for holes)Is it well organized? Is the story clear? (correct, trim, and polish)Is it accurate? (check numbers, specifications)Is it tightly written? (trim unnecessary words and information)

12

more… Step 5

Check graphics and their calloutsFind things you like and write an admiring noteRe-read the story and check your work

Step 6

Test

1. Test.2. Have someone else test.

(application engineers, customer support, UPS man)

3. Get users to test. (get hitched up through sales or customer support)

4. Study the errors and adjust your procedures.

Step 7

Rinse and repeatThe nicest thing about quotes is that they give us a nodding acquaintance with the originator which is often socially impressive.Kenneth Williams

Send feedback! Share stories and examples! Comments welcome!

[email protected]

10 7 steps to minimalist writing - ocstc · 7 steps to minimalist writing 1. analyze the user’s...

Documents