best practices for creating definitions in technical writing and editing

Creating Definitions Best practices for creating and

documenting definitions in technical writing and editing

Creating Definitions Effective Definitions

Explain an unfamiliar term using vocabulary and concepts within readers’ grasp

Tailored for different audiences by adjusting details, vocabulary & types of egs & explanations. Analytical Reports include prim/secon. readers

Anticipate questions readers/users may have; avoid multiple meanings, complexity of meaning, technical jargon & symbols

Purpose of Definitions Multiple Meanings – depends on field: focus can mean:

Localized area of disease (biology) One of the points that defines a conic section

(calculus) Location of an earthquake’s origin (earth science) Adjustment of a camera lens to specific image

(photography) Small area of a surface that light or sound waves

converge upon (physics) Rotation & elevation of a gun to hit a target (naval

gunnery)

Purpose of Definitions Complexity of Meaning – depends on

reader’s technical level. Volt can be defined as:

Standard unit of electromotive force (general diction for school & home)

Derived SI unit of electric potential defined as difference of potential between two points on a conducting wire carrying a constant current of one ampere…(technical dictionary)

Purpose of Definitions Technical Jargon – needed when technical, not

everyday, terms are used, i.e. a trade publication for plastics industry (professionals who know plastics): “ratios are indexed via a digital thumbwheel…

polyol is then added…” If new, unfamiliar terms are used to describe a

process outside the plastics industry but within the same article, definitions will still be needed even though the readers are considered “technical.”

Purpose of Definitions Symbols – nonverbal language of math, chemistry,

physics need explanation if audience is non-technical—highly educated but not trained in the discipline: E=mc2 means that energy is equivalent to mass

times the square of the constant velocity of light. E=mc2 means mass-energy is conserved. The

energy produced directly from the loss of mass during a nuclear fission or fusion reaction is equal to that mass loss times the square of the constant velocity of light.

Kinds of Definitions Formal Definitions

Found in dictionary

Tech writer may have to create a formal def for a new product or process when one does not exist or existing one is inadequate

Constructing DefinitionsPhysical Characteristics What does it look like?

What are its physical features?Comparison How is it classified?

What is it similar to?How does it differ from similarobjects (theories, procedures, situations)?

Parts/Whole What are its distinguishing characteristics?

What are its components (structural parts

and functional parts)?Function What does it do?How does it work (function,

operate)?Operation Who uses it?

What are examples of its use?

What is its value?

Format for Formal Definition

Species =Term being defined

Genus +Class or category

DifferentiaDistinguishing characteristic that separates from others in same genus

robin bird Red breast/yellow beak

robin thrush Red breast, yellow beak, black back and wing tips

Formal Definitions

Answer questions: How is it classified?How does it differ from similar objects? What distinguishes it from similar objects? What are the identifying characteristics? SpeciesHypertext is

Genuselectronically linked pieces of information

Differentiawith connections that allow users easy access between them.

Example of a Formal Definition

A modem is a device that you connect to your computer and to a cable or DSL line that allows the computer to talk to other computers through the Internet.

Informal DefsInserted/integrated casually into the text

Synonym Same Microbe+germ

What is it similar to?

Antonym Opposite Deviating/direct

What is the opposite?

Negative What it is not

Machine rivets made from metals such as aluminum, not those used in iron work…

What similar things should not be equated with this object?

Informal DefinitionsStipulation

Meaning for a particular application

In this paper, x will mean…OR“new suffixes such as .arts, .firm, .info, .non…”

What are the limitations of use?

Analogy Compares unfamiliar to familiar

Kumquat is a citrus fruit the size and shape of a pecan…

What is this similar to that reader already knows?

Illustration

Actual drawing or diagram

Sketch, drawing, etc.

What does it look like?

Operational Definitions Depends on technical profession:

Experimental researchers use certain activities to measure a variable (how it works)

Engineers specify the functions or workings of any object/process (key steps)

Answer the questions:

How does it work? How can I measure or test it? How can I determine if its function is successful? What are the steps in its operation?

Expanded Definitions

Explain and clarify information

Maintain readers’ interest

Make a doc usable for a wider audience (i.e. analytical report has primary and secondary reader/s)

Expanded Definitions Etymology – linguistic origin of a term for general

readers who find it interesting or will understand/relate to roots (see OED) How did it get its name? How old is it? Where did

it come from? History – background re development/use of subject

gives perspective on current meaning What are its origins? How long have such

objects/subjects existed? How has history affected modern development? How was original different?

Expanded Definitions Example – illustrate the application of a

term; include examples that specified audience will relate to

Informal definitions – all work together to clarify meaning for specific audience (synonym, antonym, negative, stipulation, analogy, illustration)

Placement of Definitions

Glossary – mini-dictionary; beginning when readers are unfamiliar with info & need to comprehend doc; end to refer to as needed (but must be referred to early on and boldface, itals, or asterisks)

Information notes/sidebars – use for info that interrupts flow of text—readers can use or not

Incorporated info – woven into sentences: use parentheses, -em dash (-- not - -), or commas

Appendixes – lengthy docs for readers w/varying backgrounds Online help – software co’s provide users w/ help system: balloon help, when activated a callout includes brief defs/explanations