best practices for creating definitions in technical writing and editing
DESCRIPTION
This presentation describes best practices for creating and documenting definitions in technical writing and editing. Topics covered are the following: effective definitions, multiple meanings, defining technical nomenclature, defining symbols, formal definitions, and informal definitions, and placement of definitions.TRANSCRIPT
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