Best Practices for Creating Definitions in Technical Writing and Editing

  • Published on
    17-Dec-2014

  • View
    308

  • Download
    3

Embed Size (px)

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

<ul><li> 1. Creating Definitions Best practices for creating and documenting definitions in technical writing and editing </li></ul> <p> 2. Creating Definitions Effective Definitions Explain an unfamiliar term using vocabulary and concepts within readers grasp Tailored for different audiences by adjusting details, vocabulary &amp; types of egs &amp; explanations. Analytical Reports include prim/secon. readers Anticipate questions readers/users may have; avoid multiple meanings, complexity of meaning, technical jargon &amp; symbols 3. 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 earthquakes 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 &amp; elevation of a gun to hit a target (naval gunnery) 4. Purpose of Definitions Complexity of Meaning depends on readers technical level. Volt can be defined as: Standard unit of electromotive force (general diction for school &amp; 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) 5. 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. 6. 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. 7. 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 8. Constructing Definitions Physical 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 similar objects (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? 9. Format for Formal Definition Species = Term being defined Genus + Class or category Differentia Distinguishing 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 10. 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? Species Hypertext is Genus electronically linked pieces of information Differentia with connections that allow users easy access between them. 11. 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. 12. Informal Defs Inserted/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? 13. Informal Definitions Stipulation 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? 14. 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? 15. 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) 16. 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? 17. 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) 18. Placement of Definitions Glossary mini-dictionary; beginning when readers are unfamiliar with info &amp; 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 cos provide users w/ help system: balloon help, when activated a callout includes brief defs/explanations </p>