Effective Strategies for Writing Technical Definitions

Writing Technical Definitions Technical Writing Prof. Durian

What Are Definitions, Descriptions, and Instructions? A definition is a (brief) explanation, using words and (sometimes) graphics, of an item, action, or concept. A description is a (long) explanation of an item or concept, usually accompanied by graphics, of an item, action, or mechanism. A set of instructions is a step-by-step explanation of a task (with accompanying graphics) that is intended to enable a person to complete it.

Writing Definitions Before we can write a definition, we need to establish (or define) what we re writing and why.

Why Do We Need Definitions? Definitions are used to clarify a description of a new development or a new technology technical field. Without a definition, people may disagree on what the term means. For example, a research team that creates a new drug must name and define it. Specialists also use definitions to communicate with less knowledgeable readers from other fields or the general public. For example, a manual explaining how to operate a forklift includes definitions of parts and tools.

Strategies for Effective Definitions Remember that the readers (users) may have different aptitudes than you (the writer). To ensure understanding Use Simplified English and easily recognizable terms for all definitions. Create a glossary (a list of definitions) when writing a manual or long(er) document. Pay close attention to key terms and ensure the definition is provided. Use graphics to help readers understand a term or concept.

The Three Styles of Definitions A parenthetical definition is used for clarification of a key term when it is uncertain if the reader is familiar with the term s meaning or when a less common meaning is being used. A sentence definition is used to establish context and ensure clarity as a way of introducing a major point of discussion or simply to ensure that a precise meaning is mutually understood by the writer and reader. An extended definition is used to educate the reader and elaborate upon the significance of a term and its significance, far beyond simply the meaning of the word.

Parenthetical Definitions Used to provide a brief clarification of a key term in parentheses following the term. The definition is not the main point of the sentence but simply a clarifying detail. Format: Lorem ipsum dolor sit key term (definition). Example: Linux is perhaps one of the best-known examples of open-source software (software that is free for anyone to use). Note: Do not bold or underline the term or definition in your writing; these features are used here for illustrative purposes only.

Sentence Definitions Used to provide a one-sentence explanation of the term. The definition is the main point of the sentence (hence the name of this style!). Format: Term IS [Category] {+ Distinguishing Characteristics} Example: Open-source software is [computer software] {that includes a programming code that is freely available to users}. Note: Do not bold, bracket, or underline the term or definition in your writing; these features are used here for illustrative purposes only.

Extended Definitions Used to provide a more detailed explanation of a term when the reader needs more information to understand the context or information to follow in the document. The definition is the main point of not only the first sentence but the entire paragraph, section, or passage. Writers may include a link to well-written extended definition in another genre, to give readers more context. Format: Begin with a sentence definition; then, continue to write sentences, paragraphs, and (labeled) sections as needed until the explanation is complete. You may need to explain history, common uses, (dis)advantages, characteristics, alternatives, etc. Example: IBM's extended definition of open-source software. Note: In your own project, you will write and include the full definition, not link to another source. This one is for the purpose of showing a professional example only.

Techniques for Extended Definitions When writing an extended definition, be sure to include all of the information that the reader needs for clarity. Often, you will need to do several of the following: include graphics to help the reader see, provide several examples, explain principles of operation, describe partitions, divisions, of subcategories, compare/contrast to related items/actions or parts of itself, make an analogy to something with which the reader is more familiar, summarize the history of the term s etymology, and/or negate (tell what it isn t).

Where to Place Definitions Place definitions where the reader can find them and understand the surrounding text. Common locations include in the main text (parenthetical, sentence, or extended definitions) in marginal glosses (sentence definitions) via a hyperlink (extended definitions) glossary (sentence definitions). appendix (extended definitions) footnote (sentence or extended definitions)

Basic Ethics We need to be concerned with ethics in all writing (and conduct). Yet this project that involves explaining and instructing requires additional considerations.

Principles of Conduct: Parenthetical Definitions The four key principles of conduct are 1. rights (basic needs and welfare), 2. justice (accessibility, inclusiveness, and accuracy), 3. utility (positive and negative effects), and 4. care (relationships with other people).

Principles of Conduct: Sentence Definitions 1. Rights are the basic needs and welfare. 2. Justice is a document that is accessible, inclusive, and accurate. 3. Utility is the positive and negative effects of the document. 4. Care is the relationships with other people, such as between the writer and audience.

Principles for Ethical Consideration Abide by laws on intellectual property, contracts, and liability. Comply with accessibility standards. 1. 7. Use design to highlight important information. Abide by the appropriate professional code of conduct. 8. 2. Abide by your organization s policy on social media. Distinguish between fact and opinion. 3. 9. Take advantage of your employer s ethics resources. 10. Tell the truth and never falsify data or misrepresent information. 4. Avoid discriminatory language. 11. Acknowledge assistance from others and cite sources. 5. Avoid language that attempts to mislead your readers or to evade responsibility. 6. 12. Do your best to be clear and meet the audience s needs.

Encouraging Ethical and Legal Behavior

Obligations to Employer To Uphold Do this Apply the skills and work hard. 1. Competence and diligence 1. 2. Generosity Share your knowledge and expertise to help. 2. 3. Honesty and candor 4. Loyalty Uphold truthfulness. 3. 5. Confidentiality Maintain company privacy. 4. Act in your employer s not your personal--best interest. 5.

Obligations to the Public Specific: These vary by occupation; consult with your employer. Universal: The products and services you work with need to be safe (do not injure or harm the consumer) and effective (operate as promised) to fulfill your obligations to the public.

Obligations to the Environment While your individual actions at work may not pollute or deplete our natural resources in a significant way, your organization s collective actions may. Therefore, it s important to be aware of the environmental impact of your company. Here are some actions you can take to work towards ethical behavior in obligations to the environment: Alert supervisors to damaging situations. Dispose of waste properly. Offer/suggest initiatives to reduce environmental impacts.