Difference between revisions of "Definitions and Descriptions"

...by students

If you are ever going to write instructions on something technical, please read this

Overview

Now that you know what this chapter is all about lets get into what definitions and descriptions are.

Definitions

Definitions are technical terms known only to those in your profession.

Descriptions

A good way to explain what a description it to say it is like an expanded definition. As the name implies when you are writing a description you are trying to describe something. This is different than a definition because while when writing a definition you are clarifying a technical term a description you are describing an action.

Writing Good Definitions

Even the best written document would be nothing without proper definitions. Without definitions readers will be left wondering of the meaning of certain technical terms. Including definitions when writing lets readers of less technical backgrounds know what more advanced terms are. Readers that are more advanced also benefit because they can go back and reference terms that they aren't completely sure of. When writing definitions you should use the following guidelines.

Keep it simple

When writing a definition keep it simple. Writing a definition that is overly long with other technical terms in it is just going to defeat the purpose of writing that definition in the first place. There are three formats you should choose from when writing definitions.

1. Informal Definition
   Very brief. This is often in parentheses right by the word being defined. 
2. Formal Definition
   This is a full sentence. 
3.  Expanded Definition
   This is the most lengthy of the three formats to choose from. This type of definition may be a paragraph or more.

Example

Now that you know the types of formats you should choose when writing a defintion how do you decide which one to use?

• When Should I Use An Informal Definition?
  • Remember that informal definitions are very brief and often come after the word that is being defined. Use an informal definiton when you are defining a term that most users should know. Using an informal definition keeps the reader moving and doesn't disrupt the flow of your paragraph.

E.g.
You can use a browser (Software that alows you to view pages on the internet) to make deposits into your online banking account. 

As you see here the definition comes right after the word being defined. It is short and to the point.

• When should I Use A Formal Definition?
  • A formal definition is a proper sentence. It should list three things (1) the term that is being defined, (2) a class that that term belongs to, and (3) features of that term.

E.g.
A web browser is a computer program that allows a user to view pages on the internet.

• When should I Use Expanded Definitions?
  • A brief sentence or point form note may not always be enough to adequately define a term for a user. In this case you should use an expanded definition. An expanded definition consists of three parts (1) an overview of the topic, (2) supporting information, (3) conclusion or closing comments at the end.

Common Mistakes

Writing Good Descriptions

Know your audience

Knowing your audience when writing proper descriptions is key. You should ask yourself several questions before you start writing: (Textbook citation)

• How much detail are you supposed to include in your description?
• What is the technical background of the persons who will be reading your description?
• Are all the readers of the same technical background?

Considering who you will be writing for will make sure you write something that is understandable for everyone. Remember when writing for an audience that is of mixed backgrounds that you should write for the members of the audience with the least amount of knowledge. In this way you will be sure that everyone that is to read your descriptions can understand them.

Accuracy is key

Being accurate when writing a description lets the reader understand what you are trying to describe.

Use an objective point of view

Remember that when you are writing a description you are explaining to a user the list of steps involved in a process, not telling them how to do it. Steps in descriptions should not be written in the personal point of view.

E.g.
- Objective point of view:
 The carpenter then cuts the wood.

- Personal point of view
  You should then cut the wood. 

Choose the right amount of detail

Remember to consider who you are writing for to determine how much detail you really need to include when writing descriptions.

Have an Organization Plan

Use of Analogies and Graphics

Visualizing Test

A sure fire way to test the effectiveness of the description you have just written is to give it the visualizing test. Read your description to someone who is not familiar with the topic you wrote about. If that person can draw a rough sketch of what you are describing then you have a good description.

Examples