Jerz > Writing > Technical

This document describes how to write a mechanism description (also called an object description).  A mechanism description is a short report designed to convey to the reader a technical understanding of the function, appearance, and operation of a particular object. In one or two sentences, give the reader a quick overview of these three elements, before you launch into separate sections with details.

There is no universally “correct” organizational structure that applies to every writing situation in every discipline. If you can find a good model of the kind of thing you’ve been asked to write, you’ll be better off using the organizational and headings of that model, rather than uncritically following the structure I suggest here.

We live in a tl;dr world. Any professional document more than a few paragraphs long should start with a summary, for the benefit of a busy reader who may be reading hundreds of similar documents each day. (Your reader reads the summary first, but you should write it last.)

• See “Sentence Definition: Species = Genus + Differentia“
• If you are writing about a sequence of events, see Process Description.

A mechanism description analyzes (that is, subdivides into components for further scrutiny) an object in space. When you try to organize your major subsections, if no other obvious pattern seems appropriate, you can always fall back on the more-important-to-less-important strategy.

• Don’t sell the object.
  A technical writer is not required to persuade the reader that the object is wonderful, or valuable, or scary. But do mention the details. While you shouldn’t say an object is “adorably cute,” you could mention that it “resembles a cartoon cow wearing a pink ruffled skirt,” and let your readers make the value judgment for themselves.
• Just describe it.
  Provide whatever level of detail your reader requires. Know your audience.  A child safety organization may require an extremely detailed description of a simple toy (along with a separate process description for the manufacture of each component), while a military recruitment office might require only a few paragraphs about a complex nuclear submarine.

Introduction

Your introduction should first state the purpose and scope of your document.  If your document is longer than a few paragraphs, the first paragraph should be a stand-alone summary, which briefly defines the object and explains its function, appearance, and operation.

Throughout the ages, mankind has found many uses for salt.  Ancient tribes used it preserve meat; around the world it adds flavor to food; the Bible uses it as a symbol of zest for life.  Salt became such an important part of people’s diet that a way was needed to allow early nomads to carry salt with them on their perilous travels; such a device ideally also helped ancient gormandizers to distribute portions of the precious flavor enhancer onto their foods.  Thus was born the salt shaker.

Some beginning technical writers, who remember using grandiose words to please their high school English teachers, mistakenly believe that an introduction should provide a sort of cosmic overview. But a technical writer does not need to amuse or impress a reader — somebody who wants to know exactly how much this salt shaker weighs does not need an ancient history lesson. Just provide the necessary information as efficiently as possible.

This document provides the manufacturing specifications for the entire line of Happy Homemaker “Praying Cow” salt shakers (Divine Bovine Industries model #00045).  A hand-painted ceramic collector’s item, the “Praying Cow” salt shaker represents a plump, cartoon-like cow, her head bowed as if in prayer.  A blue flower-print skirt is painted onto the body of the animal.  The salt is dispensed through the cow’s matching bonnet, via a circular array of six small holes.  The bonnet twists off to allow the consumer to fill the dispenser cavity.

Note that this writer correctly begins by introducing the reader to the document.  We can assume that the rest of the document provides the measurements and other technical details, as promised by the opening sentence. The summary paragraph assumes that the reader already knows the definition and function of a salt shaker; this is permissible. In this case, it would not be wise to omit a description of the appearance, and almost unforgivable not to include a picture. Fortunately for civilization as we know it, this product is completely imaginary.

Function

Answer the question, “What does it do?”

• Keep this section brief — chance are, if your reader is interested in a full mechanism description, he or she already has some idea what the object is for.
• Of course, if the object will be so unfamiliar to your reader that the rest of the document won’t make sense, then provide whatever background information your reader is likely to need. (Sometimes the only way to do this is to show a prototype of your mechanism description to a test user… see “Usability Testing.”)
• If the object participates in a process, then you may need to write a brief process description as well.

Appearance

Answer the question, “What does it look like?”  You may have to use classification to break a complex object up into its various components, and describe each in sequence.

The original Star Trek Enterprise, TV’s most famous fictional starship, has a saucer shaped primary hull, a cigar-shaped secondary hull, and two cylindrical warp pods.  A horizontal strut suspends the secondary hull behind and below the saucer.  At the flat, front of the suspended section is the deflector dish, and at the tapered back are clamshell doors that open to reveal a shuttle bay.  Each of the two cylindrical power units is supported by a long pylon connected near the rear of the secondary hull.  The pylons raise the power units above the plane of the horizontal dish, and extend them outwards roughly to the same width of the saucer.  The pods themselves have red semicircular half-spheres on the front, and tapered cylindrical fixtures on the rear.

The content of the above section is fine, but it’s a little hard to read.   If you were to go in to any more detail, you should break it up into smaller paragraphs… If you start to break your object up into multiple nested layers of components, you should consider a bulleted list, formatted so that your reader can more easily identify the level of detail you are describing in any given section. (See below.)

OVERVIEW The original Star Trek Enterprise, TV’s most famous fictional starship, is composed of a saucer shaped primary hull, a cigar-shaped secondary hull, and two cylindrical warp engines. 1)  The SAUCER-SHAPED PRIMARY HULL contains the following visible features: The bridge (a circular, domed structure at the center of the upper surface of the saucer). The first pilot episode, “The Cage,” featured a special effects shot of the camera zooming in on the top of the model, to reveal the characters arranged on the bridge. The set for the bridge on Star Trek: The Next Generation featured a ceiling window that revealed a starry backdrop; however, but no such window ever appeared in the original series. Lighting effects (including blinking running lights, as well as smaller lights representing windows) Vessel identification (black painted capital letters on the upper and lower surfaces of the saucer, reading “U.S.S. Enterprise” and “NCC-1701”) Phasers and photon torpedoes (usually depicted as emanating from a spot near the center of the underside of the saucer) 2) The CIGAR-SHAPED SECONDARY HULL contains the following visible features: (Etc.)

The above revision breaks up the imposing block of text, and uses spacing and bolding for the benefit of readers who are scanning for specific information.

Operation

Answer the question, “How does it work?”

You could also productively think of this section as the conclusion to your paper.  Rarely will you gain anything by writing a cookie-cutter, boring conclusion like, “Therefore, this paper has shown that the PickMaster 2000 Electric Toothpick Dispenser can be an exciting part of the environment around the cash register in any restaurant.”

Even if an object does not have an exciting or visible method of operating (such as a decorative item or a simple brick), the conclusion should still explain how its design helps it to fulfill its function.

Fall, 1998 — written by Dennis G. Jerz
14 Feb 2001 — first posted in Online Reading Room
12 Sep 2003 — minor updates
04 July 2011 — minor updates
15 Jan 2018 — reformatting; further minor updates
23 Mar 2018 — updated graphic; minor tweaks