Home Technical
Writing
Information
Design
DITA
Exchange
News and
Articles
About Contact

The Technical Writing Rule I Learned From Nursery School

Originally published in the November 2002 edition of Forward, the Newsletter of the STC UK Chapter


About 15 years ago, an American clergyman published a book of thoughts and reflections which became an instant best-seller and is still in print.
In All I Really Need To Know I Learned In Kindergarten, Robert Fulghum reminded readers that some of things we are told when we are very small can be useful in later life as well.

The world would be a better place, thought Fulghum, if we always remembered rules like: "don't hit people", "don't take things that aren't yours", and "say you're sorry when you've hurt someone".

Wouldn't it be wonderful for the future of the planet if governments adopted environmental policies based on principles such as "put things back where you found them" and "clean up your own mess"?

When my own children were smaller, they too attended nursery schools, and I believe that their early experience of playing, learning and sharing with other children was very important for them. When I would collect them at the end of the nursery day, I picked up one or two things from their teachers that were important for me too.
One of the phrases I heard then has stuck in my mind, and sounds like it could well have come from Fulghum's book. It has become something of a touchstone for me in my recent work as a technical writer for a software development team, as it can guide me in deciding what to put in to the documentation, and what to leave out. Occasionally, the software developers where I work are rushing to push their latest and greatest feature out to an unsuspecting user community. Their enthusiasm has a price - there are always dozens of warnings and caveats to go with anything that hasn't been thoroughly tested.

"If the users do A, then they mustn't do B, or if they do C they shouldn't do D, unless they increase their RAM and upgrade their processor. And if they try it on Linux it will probably crash. And it all needs to be in the Release Notes. By yesterday."

"But why?" I ask plaintively. "If this feature's not ready, why put it in? And if you need to put it in so you can test it, why tell the users about all these problems that just make our product look bad?"

Sometimes I convince them, and sometimes I don't. I only wish they could have heard what I heard the nursery teacher say that day:
"If you can't say something nice, don't say anything at all".

David Farbey,
Senior Member, UK Chapter

Copyright © STC and David Farbey 2002. All rights reserved. Links to this article, and properly acknowledged quotations from this article which include a link, are welcomed.

Valid HTML 4.01!
 
Valid CSS!