Chapter 21 – Preparing Instructions and Manuals

Chapter 21 – Preparing Instructions and Manuals

Chapter 21 provides excellent guidelines and information on how to create effective and usable instructions. Instructions have to be usable because someone will depend on that instruction to tell them how to perform a task. Analyzing your audience, task, & genre, effectively using text and visual content, and understanding learning principles will greatly aid you in creating effective instructions.

Principles of Adult Learning

Malcom Knowles researched characteristics of adult learners and comprised this list:

Self-concept. Instructions allow user to asses their prior knowledge and the instructions point user to appropriate place (like a search feature in a electronic help file).

Rationale. People generally like a reason as to why they should do/learn something.

Experience. Analogies and examples, when used well, can enhance learn-ability.

Orientation. Focus on the practical information: what, why, & how.

Motivation. I didn’t quite follow how Burnett ties motivation in with better instructions…something like options to instructions/manuals will appeal to a broader range of motivations I think.

Burnett points out a key factor to consider when developing instructions, aliteracy. People who are aliterate can read, but choose not to. This can be caused by any number of things: don’t have the time, don’t think they need to, or simply don’t want to. Some typcal characteristics of an aliterate reader are…

Scanning text, but not reading the text.

Depending on visuals rather than words for information.

Imbuing color, shape, position, and size with meaning to avoid writing language. I think Burnett means someone sees a picture in an instruction and says, “that’s how it should be” and doesn’t bother reading the instructions.

Analyzing the Task

Burnett identifies 4 categories of instructions…

1. Actions/behavior of personnel

2. Assembly of objects or mechanisms

3. Operation of equipment

4. Implementation of a process

Figure 21.1 on page 779 has four sections with questions to ask yourself when analyzing the task for your instructions.

Section 1 gets you thinking about the steps and detail required for the instructions. Section 2 considers the context in which the instructions will be used.

Section 3 takes into account constraints to completing the task

Section 4 wants you to start relating the task to the audience.

Analyzing the Audience

User-friendly instructions start with the author having a personal interest in the user and the instructions. A conversational tone, using “you”, and action verbs (like turn, push, adjust, etc…) are completely acceptable and help cement the link between instruction, user, and task.

It’s also very important to chunk and label your information effectively as this helps the user distinguish identify and distinguish information. A simple example is don’t bury safety points in the middle of a block of text, keep them separate and preferably in the front of the document to immediately alert the user of safety concerns.

It’s also important to consider international audiences. The world is getting smaller every day and having instructions in multiple languages is required for some products sold world wide. However, instructions that can be effectively depicted entirely with visuals can be universally “read” and understood by anyone from any country. Pages 786 & 787 provided pointers for designing instructions for international audiences, but I though a lot of their points can be applied to all instructions…

• Be consistent in the way words, links, and visuals are used.
• Use visual cue to indicate sequence or direction (like numbered steps or arrows indicating direction/orientation)
• Visually distinguish main steps from details/explanations (font size, type, style, etc..)

Choosing a Genre

The purpose, context and delivery format of your instructions affect how you should plan and design your instructions. Figure 21.6 on p790 provides several examples of purpose and delivery to give you an idea of the different genres of instructions. A key distinction to be made is that between short instructions and manuals. Manuals contain much more information and it’s important to provide users multiple ways to access that information based on their needs (table of contents, glossary, information chunking & organization)

Content

When considering your contend you need to think about your purpose and have a goal statement that matches that. You also want to have clear direct accurate information that people can understand and rationalize with.

­Purpose

You need to stick to your purpose so you don’t put any doubt in the viewers mind. Many time the purpose is stated in the title or with the visual aids.

Necessary components

This is where you list all the necessary steps to get the user to the end goal.

Order

Make sure that it is in chronological order. (in most cases)

Select Grammatical Style

This is where you decide if you want to use a short hand version or proper English.

Selecting Visual Aids

You want to select the aids that don’t confuse the user but rather give better instruction than the words.

When using visual aids you need to make sure that you make sure everyting is very clear so that you can be held liable.

Chapter 20 Preparing Reports

Preparing Reports
· When you plan a report you need to ask yourself questions to determine the purposes, determine the formality , identify the audiences, decide how the report should be organized, and select the genre.

Determine the Purpose
Reports fall into one of three categories.
· To report information
· To analyze information
· To persuade readers
Writing a purpose statement gives a clear focus for a report and provides you with a way to control content and organization. A purpose statement should be placed at the beginning of the report and should state the problem, identify questions and activities related to the problem, and explain the ways the report responds to the problem.

Assess the Formality
Reports can be informal or formal or anywhere in between. Informal reports are fine when the writer has regular contact with the readers because they probably already know the background. Informal reports can be written as memos, letters, or short reports. Formal reports are used when the writer isn’t in regular contact. The background needs to be included and more documentation is required. Front and end matter are included in formal reports such as a table of contents and references. Determining whether or not to write a formal or informal report is based on the relationship the writer has with the reader and what they need to know.

Identify Audiences
Knowing the audience helps clarify purpose and organization. There are two different kinds of readers.
· Primary Readers: those who will use the recommendations for decision making and those who will be interested in the technical details.
· Secondary Readers: those indirectly affected by the conclusions and recommendations of a document

Organize the Information
1. Overview: This section states the purpose and/or problem.
2. Background: This section presents information dealing with methods of investigation as well as materials and equipment used. (optional)
3. Recommendation: This section identifies conclusions and/or recommendations.
4. Evidence: This section presents the results.
5. Discussion: This section explains or justifies the conclusion or recommendations.

Select a Genre
Information can be presented in prepared forms, memos, letters, or formal reports.
· Prepared and memos can be a routine task. Memos, letters, formal repots can be a non-routine task.
· Prepared forms, memos, and formal reports can be for internal audiences. Prepared forms, letters, and formal reports can be for external audiences.
· Prepared forms, memos, and letters can be written with an informal tone and format. Letters and formal reports can be written with a formal tone and format.
Types of Reports
· Research Reports and Articles should be accessible, open to analysis by peers and available to the public. It should be transparent, clear in structure, process, and outcomes. It should also be transferable, useful beyond the specific research project.

· Task Reports
o A recommendation report or justification report presents or defends specific suggestions or solutions for a particular situation
o An inspection report or examination report focuses on recording observable details, sometimes followed with recommendations.
o An information or investigation report is the result of an investigation that collects and evaluates information about some existing situation, but a recommendation isn’t always required.

· Periodic Activity Reports are usually used when the work is routine.
1. Overview: Identify projects
2. Activities: Specify project activities that are completed, in process, and planned.
3. Recommendations: Establish needed changes in scheduling, personnel, and budget.

· Progress Reports answer some questions like:
o How is the project going?
o Where are we now?
o Are we on schedule to meet our completion date?
1. Overview: Introduce the project.
2. Progress: Summarize the project to date.
3. Recommendation: Identify major recommended schedule changes.
4. Evidence: Provide reasons for changes.
5. Discussion: Discuss the impact of the proposed changes.

· Meeting Minutes provide a record of the discussion and decisions that occur at meetings, serving as official records.

· Trip and Conference Reports: The information is usually incorporated into a logically organized clearly stated report.

· Trip/ Conference
o Purpose
o Primary task
o Personal role
o People contacted/ Sessions attended
o Questions raised/ Information gainedConclusions

Chapter 19 Preparing Proposals

Chapter 19 Summary

A proposal is a document that is presented as a plan to do something new or change something in an organization or business. A proposal may be used in a variety of situations. A proposal generally includes some or all of the following information on it:

· Situation

· Plan

· Benefits

· Approach

· Evaluation

· Qualification

Proposals are different from reports, as the former is a document mentioning approaches to an answer while the latter are about information that have already happened, or they present an answer.

Proposals are a form of persuasive writing, that attempt to convince an audience that the proposed plan is a good solution to an existing problem. Proposals can have one of several purposes:

· Solve a problem

· Investigate a subject

· Sell a product or service

Types of Proposals

A solicited proposal is written in response to a Request for Proposal (RFP). An RFP provides a problem, i.e. the specifications for a proposal; a successful proposal must adhere to those guidelines and provide a viable solution.

A proposal that is submitted without an RFP being issued is called a unsolicited proposal. This type of proposal is written not to an RFP but to a perceived need. Unsolicited proposals are often internal documents, responses perceived need by someone in an organization.

Sources of RFPs

· RFPs are regularly issued by several types of organizations:

· research and nonprofit foundations

· educational institutions

· government agencies

· private business and industry

Using Persuasion in Proposals

When writing a proposal, one should take into consideration all the potential arguments and concerns that could be raised when reading the proposal. Writing effective proposals requires persuasion, which should not be confused with manipulation. Persuasion means applying credible and logical arguments to convince readers that the writer's view is appropriate.

The following factors have been identified as critical aspects of persuasion since Aristotle described them in his Rhetoric in the fource century of BCE:

· Audience Concerns: The most important aspect of preparing a proposal is "Establish that the problem or opportunity exists and then clearly show how your plan addresses it." The proposal writer must clearly suggest why the changes will be beneficial to the readers and/or listeners to negate the effects of cognitive dissonance, a principle that believes that people reject or at least devalue information that conflicts with their existing beliefs.

· Persuaders' Credibility: Credibility is making the readers believe that you are reasonable, honorable and display goodwill. Credibility, even though a political issue, greatly affects the acceptance or rejection of your proposal. The more drastic changes your proposal suggests, the more credibility is required for your proposal to get accepted.

· Logic of Message: A proposal must be logical and also based on sound assumptions, providing with it valid and reliable evidence. Also the proposal must acknowledge and respond opposing views. There are two ways of reasoning your ideas

o Induction: Induction is reasoning from the particular to the general.

o Deduction: Deduction is reasoning from the general to the specific. Traditionally, this reasoning takes a three-part argument:

§ Major premise - general statement about an entire group

§ Minor premise - state about an individual within the group

§ Logical conclusion - conclusion about the individual

Considering Requests for Proposals

To write an effective proposal, the writer needs to understand the RFP writer's point of view. To understand that, the writer should be good in writing an RFP himself as well.

· Writing an RFP: The preparation of an effective RFP includes several steps:

o Identify the Problem or Opportunity

o Provide Background Information

o Define the Desired Outcome

o Specify the Product or Service You Need

o Require Detailed Information about the Organization or Personnel - information such as personnel, available equipment, and work history.

o Provide Process Information - information such as dates, project details, proposal submitted for consideration, criteria for evaluating the proposal

o Establish Criteria for Selection

· Managing the Proposal Process: Managing the proposal process involves responding to general questions from vendors, consultants, or researchers, coordinating the schedule for submission of proposal, evaluation of proposals and the responses about acceptance or rejection to those who submitted proposals.

Preparing Proposals

According to the NIH (National Institutes of Health), the 10 top reasons proposals were rejected were as follows:

1. Lack of new or original idea
2. Diffuse, superficial, or unfocused research plan
3. Lack of knowledge of published relevant work
4. Lack of experience in the essential methodology
5. Uncertainty concerning the future direction
6. Questionable reasoning in the experimental approach
7. Absence of an acceptable scientific rationale
8. Unrealistically large amount of work
9. Insufficient experimental detail
10. Uncritical approach

Making sure that none of these criteria fit in your proposal will dramatically increase the chances of assisting the creation of your proposal. Also, being acquainted with the subject you are proposing will also help a lot as well! (Go figureJ)

Planning

When preparing proposals, the preparation should go smoothly if the project is planned well. This means by following the next guidelines, the proposal should go well:

1. Be aware of deadlines
2. Create a well structured schedule for completing the proposal
3. Understand the criteria grading your proposal
4. Understand what the background knowledge of the decision makers are

Being aware of the deadline is VERY crucial because by missing the deadline, your proposal will not even be considered most of the time!

When we are originally planning, these few things should be assumed in the creation of your plan:

1. Read and reread what is the purpose for the proposal
2. Identify and substantiate the problems or opportunities you are addressing
3. Meet with the key people involved to discuss the problem
4. Propose a plan that can solve the problem effectively
5. Organize the plan to an outline form
6. Understand the evaluation criteria
7. Analyze the competition’s views
8. Acquire others view points on the idea
9. Create a manageable budget for implementing the proposal

Drafting:

When drafting the proposal, it is important to turn back to the RFP. These next pointers should assist during the drafting stages:

1. If an RFP exists, follow it exactly. If there is no recommendation, use the one that is used in the book
2. Establish a solid link between the problem and the plan.
3. Provide as much information as possible. Even in the implementation stages.
4. Create arguments and counterarguments to address potential objections.
5. Use specific details and examples to show more strength in the idea you are presenting.
6. Use a “you” attitude when possible and appropriate

Budgeting:

Most proposals will require a budget narrative (or walk through) of your plan. Unless asked to be proposed in another way, a budget plan can be proposed in one of three ways:

1. Add a column to the budget summary and provide an explanatory sentence for each item line
2. Add a footnote reference to each line item and list the explanatory sentences in footnotes directly following the budget itself
3. Provide a separate subsection in which you explain the rationale for each category

Also, funders often begin reading proposals by turning to the budget and budget narrative. By doing this, they are attempting to understand the focus of your material.

Evaluating:

Once the draft is complete, it now must be evaluated. In this case, some general guidelines that should be followed while evaluating are:

1. Determine if the RFP directions have been followed
2. Make sure the draft meets or exceeds the criteria for the evaluation
3. Examine the accuracy of the technical document
4. Study the feasibility of the plan
5. Review the acceptability of cost
6. Solicit reviews of the draft from colleagues

Revising:

Once the evaluation of your proposal from yourself and your other reviewers are completed, you should have some general ideas for revising the proposal. On top of those issues that you find, these other issues should also be addressed:

1. Add, modify, or delete information to meet RFP evaluation criteria
2. Make sure the argument is coherent
3. Check to make sure the document design conforms to the design specifications

Organizing and Submitting Proposals

There are many different ways proposals can be arranged.

Sequencing Information:

If there is no specific sequence required for the proposal, this one should work well.

1. Introduction
2. Plan
3. Benefits
4. Approach
5. Evaluation
6. Qualifications

By submitting a proposal like shown above, this will make a solid, general proposal outline for the evaluators.

Submitting a Proposal:

In the past, it was typically known that a proposal would be done in written form. However, now people will do so online or in an oral presentation form. The main reason that the online form is becoming the norm is because:

1. Money
2. Time
3. Space
4. Flexibility
5. Data Protection

A strong oral presentation will also strengthen a proposal because not only can he say what is on the proposal, but he may also adjust his words towards his audience.

Ch. 17 (Again...)

**NOTE: There has been a little confusion over which group was assigned Ch. 17 so we both ended up writing summaries for the same chapter.

Effective oral communication is a critical component in any job or profession. The book states “the ability to communicate ideas and plans effectively in front of an audience” is the most important career skill according to more than 700 managers.

TYPES OF PRESENTATIONS

Informal Presentations: This type of presentation usually takes place in some type of weekly business meeting. It consists of professional peers and is considered informal because the audience is probably already familiar with you and your work. Another example of an informal presentation occurs with special interest groups or community members. In this case, individuals want to learn new information that you present and is usually followed up with a discussion.
*NOTE: Informal presentations require adequate preparation and organization. The “informal” aspect solely means you are already familiar with your audience or the information you are providing will act as a catalyst for discussion.

Formal Presentations: These types of presentations generally take more time and effort because you are presenting to an audience that is not familiar with you or your work. For your audience, including sufficient background information in your presentation is essential.

Class Presentations: This type offers important feedback that is honest and helpful from the audience. The audience can give you constructive criticism as well as point out particular positive aspects of your presentation.

PREPARING A PROFRESSIONAL PRESENTATION
Being able to identify who your audience is will help you to specifically tailor your presentation so it best fits them. Possible audiences may include:

Professional peers: They are knowledgeable and understand your field of work. Your presentations towards them should be carefully organized and include supporting evidence.
Non-expert Professionals: They have an understanding of your field of work, but are less familiar with specific technical jargon and may not be up to date on current theories or practices.
International Audiences: Requires you to become aware of particular cultural customs and/or expectations for both courtesy and effectiveness.
General Audiences: This type includes a wide variety of individuals with varying needs and interests.

PURPOSE OF PRESENTATIONS
Clearly defining the purpose of your presentation will help you identify the primary and secondary goals for your own presentation.

Informative presentations: Gives audience verifiable information usually for decision making or background purposes.
Persuasive presentations: Tries to persuade your audience for or against a particular product, proposal, or position.
Demonstration: Informs your audience about how something is done by demonstrating and explaining the process.
Training sessions: Utilizes hands-on experience by teaching your audience how to do something.

ORGANIZING A PROFRESSIONAL PRESENTATION
1) Create an audience-centered atmosphere
Research who your audience is and appropriately relate comments and content that are relevant and interesting to them.
2) Encourage active involvement
Try and get your audience involved as much as possible by including them in demonstrations.
3) Make what you say easy to listen to (and remember)
Make your stories brief and to the point. Also, make connections between the new information you are presenting to previous information your audience may already know.
4) Vary the pacing and structure of your presentation
Avoid overwhelming your audience by cramming too much information in your presentation. Alternate between difficult material and easier material.

**Make your presentations easy to follow with good organization, structure, and transitions. Also, utilize note cards or outlines to help guide you through your presentation without getting lost or off track.

PREPARING MATERIALS FOR A PROFRESSIOAL PRESENTATION
**Visuals are very valuable and aid in the understanding of your presentation. Visuals help clarify complex concepts and help reinforce the content of your message. Visuals are separated into categories: charts, diagrams, schematics, graphs, tables, maps, drawings, and photographs. They help in organizing and supporting your information as well as encourage attention and engagement from your audience.

**Visuals may be presented in several ways including white boards, flip charts, slides, posters, etc. It is important to keep in mind the size and color of your visuals in relation to your audience and physical environment.

**The use of PowerPoint for oral presentations can be useful for several reasons. However, try to avoid cramming too much information in a slide. Try to ensure usability by including appropriate key concepts in a slide and making it easy to read and follow. Also, do not use PowerPoint to simply read word for word your presentation. Use the slides as an outline to help you with key points.

**Handouts can be useful by giving your audience something tangible to follow as well as take notes or refer back to later.
-->Handouts should be stapled together or somehow attached.
-->Usually distribute handouts either at the beginning or end of your presentation.
-->Include enough detail in your handouts to highlight key points and reinforce main topics from your presentation.
-->Explain to your audience when to refer to a particular page in your handout.
-->Only include handouts if it will enhance your presentation.

**Make posters aesthetically appealing and easily readable to ensure proper accessibility, comprehensibility, and usability.
**Create and maintain a professional appearance by avoiding behavior or appearance that may distract from the presentation.
**Remember vocal characteristics such as: loudness, clarity, tone, and rate.
**Adequately prepare yourself for questions from the audience

EVALUATING PRESENTATIONS
The process of successfully and fairly evaluating a presentation involves actively listening to the presentation. Being able to assess oral presentations will not only help others increase their effectiveness, but assist you as well.

Ryan Kniefel & Andrea Kircher
Ch. 17 – Engaging in Oral Communication
Chapter 17 talks about how to communicate ideas and plans effectively in front of an audience. It explains how to organize your thoughts and ideas into a well organized presentation through the use of outlines, visuals, and the type of audience you will be presenting to.
Types of presentations:
Informal Presentation- Usually consists of discussion. The audience is a group of peers or people already familiar with you and your work.
Formal Presentation- Audience is not familiar with you and your work. Requires more preparation and detail in order to give the audience background information about the topic.
Class Presentations- Very helpful in strengthening your oral presentation skills. A benefit of class presentations is the honest feedback you can receive about your strengths and weaknesses.
Audiences:
Professional Peers- Assume you have high degree of technical expertise, tend to ask more difficult, in depth questions.
Non-expert Professionals- Includes people in decision making positions; Want the technical information but don’t need to receive the in depth details.
International Audiences- Appreciate awareness and respect of their culture. Like to see visuals in the presentation for better clarification.
General Audiences- Appreciate clear purpose, defined terms, useful analogies, examples, and visuals.
Types of Presentations:
Informative Presentation- gives the audience verifiable information
Persuasive Presentation- attempt to convince audience about advantages of accepting a particular proposal or position.
Demonstrative Presentation- Shows audience how to perform a certain task.
Training Session Presentation- teaches audience how to perform a task usually with hands-on experience. (Training for a job)
Engaging your Audience:
Strategy 1- Create an audience-centered atmosphere. Find out something about your audience in advance so you can come up with examples that will relate to them.
Strategy 2- Encourage active involvement. Get the audience involved through discussion, questions, or demonstrations.
Strategy 3- Make what you say easy to listen to and remember. Don’t overload audience with information by rambling on with stories. Stick to the point.
Strategy 4- Vary the pacing and structure of your presentation. Don’t be monotone. Make presentation exciting.
Visuals:
Examples: Charts, diagrams, schematics, graphs, tables, maps, models, drawings, and photographs
Visual memory is stronger than auditory memory. Use visuals to help refresh the memory of the audience
Power Point Presentation:
One if the most effective tools for oral presentations. Use the power point as an outline for the presentation. Do not read of off the slides!!!
Handouts:
The use of handouts can be very effective. Handouts give the audience a reference and a place to take notes.
Professional Appearance:
Wear appropriate clothing- Wear clothing that you are comfortable in. Avoid wearing shiny jewelry that will distract the audience.
Handle Notes Comfortably- Number the notes or cards so you are not fumbling around trying to find the next one.
Make Eye Contact- Making eye contact with the audience shows confidence.
Handle Mistakes Smoothly- If you happen to make a mistake, apologize and continue on.
Relax Your Hands- Don’t fidget around with hands. Relax hands by resting them on the podium or along your side.
Relax Your Feet- Wear comfortable shoes. Don’t sway back and forth.
Move Naturally- Avoid nervous actions. Move naturally and comfortably by focusing on what you are trying to say and not on how you look.
Use the Podium Comfortably- Don’t lean or clutch on the podium.
Vocal Characterization:
Volume, pronunciation, rate, and pitch are important factors when giving a presentation. You must speak loud enough so that everyone in the room is able to hear you. This may require the use of a microphone in some situations. Well pronounciated words will eliminate the audience from any confusion in your presentation. Avoid racing through your presentation. This will cause your audience to be overwhelmed. Present the information in an average rate of speed. The pitch of your voice in a presentation is a key factor in how your audience will respond to you. Have liveliness in your voice when presenting information, monotone speakers can cause the audience to lose interest.

Chapter 12 Using Visual Forms

· Visuals not only attract attention and add appeal; they also strengthen documents in other ways.
o Visuals can be more specific than text. An example from the book suggests that the word tugboat can represent anything from “Tommy Tug” from the children’s story to barge tugboats. The use of a visual is easily identifiable.
o Well-designed visuals can usually be understood more easily than text. When you are working with numbers a graph might be a more effective way to convey what you want to say than text. Most people are better able to process and remember trends that are presented in graphs and charts.
· Visuals can be very important to increasing the accessibility and usability of your documents.
· It is important that you how to incorporate visuals into a document, as well as understand specific functions of visuals in technical documents and, conventions in using color.
o Visuals should illustrate explain, demonstrate, verify, or support the text
§ There are four basic layouts for visuals and text.
· All text
· Text with supporting visuals where there is mostly text.
· Visuals with supporting text where there are mostly visuals.
· All visuals.
· Visuals can be adapted to different audiences by the complexity of content, presentation, color, and size. When you are presenting to non-experts you may need simpler and more frequent graphs and pictures.
· You should refer to visuals in the text, rather than just include the visuals and expect the audience to make the connection. Include enough information in your text reference such as a figure number and title.
o Labeling: Complete and accurate labeling of visuals makes them easier to use. Identification, title, and caption are all required for complete labeling.
o Placement: In most cases you want to place the visual as close to the text reference as possible. Surround visuals with white space to separate them from the text of the document.
· Visuals fulfill one or more functions in technical documents. There are seven major functions.
o Function 1: Provide immediate visual recognition.
o Function 2: Organize numeric or textual data.
o Function 3: Show relationships among numeric or verbal data.
o Function 4: Define or explain concepts, objects, and processes.
o Function 5: Present chronology, sequence, or process.
o Function 6: Illustrate appearance or structure, which may include describing objects or mechanisms.
o Function 7: Identify facilities or locations.
· Color is a great way to add to your document using color effectively is important.
o Overuse of decorative color contradicts the basic functionality of the document.
o Too much color can distract or annoy the reader.

Chapter 15 - Technical Description

Technical description is basically giving a characteristic to a person, place, or thing. Questions about size, color, purpose, and importance could be answered. The depth in which you describe something can vary from a few words to a few pages depending on how detailed you want it to be. Technical Descriptions are very important in that if not given enough emphasis, a reader might underestimate its importance. When deciding how to describe something ask yourself:

• Will a description help accomplish your purpose of providing info, persuade readers or listeners, or help them complete a task.
• Will a description help people gather info, make decisions or complete an activity or action
• Will it help prevent problems

Technical Descriptions are used in many different fields. They can help new employees learn how a program work or instruct students on how to set up or use the campus website. However they are used, they can help make thins easier and more understandable. Using simple readable words letting the reader know it is “you the reader” I am projecting my information to are key in helping someone use this information. Also Giving specific information related to the field, Making sure the materials are easily comprehensible and accessible so it can be easily found.

Ways that Technical Descriptions may be used.

• Technical Manuals- describe mechanisms or systems that the manual deals with
• Training Materials- helps teach someone how to do a task or how to use a helpful tool
• Proposals and Reports-gives an overview then appropriate details directed at the reader
• Marketing and Proposal Pieces- usually give information and then tell the positive sides of it. They will try to persuade you into liking or putting there product or material.
• Public Information and Education- gives substantial information and descriptions about things simply because people need to be informed before making decisions about things

When deciding what information to give to the audience, you must first answer some questions. What is the task, and what do they want to know? Are you trying to help them make a decision, or do they just want a simple overview? Answering these questions will help the reader stay interested as long as you direct the technical descriptions to their needs.

Two components of descriptions:

• Structural parts comprise the physical aspects of the device, without regard to purpose.
• Functional parts perform clearly define tasks in the operation of the device

When conveying the descriptions to an audience you must very precise so that your information is verifiable. Three ways of doing this are…

• Audience –Appropriate Terms- The audience is what you want to think about when deciding how specific of info you want to give. Non experts need more detail than do experts and would probably need the details in simple terms.
• Accurate Terms- Make sure that you clear and concise words when describing things. One good example is when someone says ball, a ball is supposed to be a round object but not always. A triangle is different than a pyramid. If you find the terms you want to use to be more difficult or unclear to your audience you may want to use different words or even a diagram.
• Figurative Language- another way to ensure precision is to use metaphors, similes, and analogies that are clear and appropriate descriptions for the audience.

Visuals
Visual Aids are another great way to help the audience understand what you are telling them. The visuals can be anything from photos to videos, as long as it helps the reader form a mental picture. Some descriptions are difficult without visuals so put some thought in when deciding how to describe them.

Organization
Organization is a critical factor when designing any technical document. You want make sure that is easy to follow and make sure every step is understandable and concise. Descriptions should be titled so it is easy for someone to identify. The beginning should be a small overview of the overall purpose. Some Directions use history background that would interest the reader. The body of the description should be part by part and explain the purpose of the document At the end, a conclusion can be incorporated by stating use, benefits/problems and, who uses it, although not all descriptive documents have a summary and just end with the final step.

Chapter 13 - Designing Electronic Communication

In this chapter the book covers how to effectively use and understand the principles of effective electron communication. They focus more on web base systems since that is the way of the future.

Electronic communication can be categorized into 3 different groups. The first is Interactive and non linear, which means multiple possibilities among users. In other words one person can use it for one thing and another can use it for a total different purpose. The second group is virtual or open, which allow people to view things in a made up place and being somewhere without actually leaving home. The third and final, is complex and dynamic which is planning for different users and technology.

Today there are many different types of electronic communication devices out there, such as the computer, PDA, Cell phone, ect.. This is making electronic communication more important than it ever has been.

Since websites have became an important way to feed the public information it is very important that you take the following into consideration when designing a page.

1. Page size- You want to maximize what the user can see on the screen at one time.
2. Legibility- How easy someone can read what is on your page? You need to take into consideration what backgrounds you use along with font type and size to make it as easy as possible for user to see.
3. Responsiveness- how quick it is to respond to users clicks. You don’t want the user to become unhappy waiting for you page to load.
4. Navigation- you want to make it easy for users to get around your site.
5. Equipment- make sure you have quick enough equipment

When designing a page you need to take in to consideration how you wan the person to navigate through the pages. Many times you will have pages that you would like the user to see more often so making them much easier to click on is a great way to get them to that page. But most importantly when thinking about the navigation you want users to be able to go back as easy as they go forward.

There are 3 things that go into a good webpage.
1. Information Architecture
Within information architecture you can separate it into 3 different subcategories. The first is organizing the information, you need to think about all you info and how it relates to each other and separate it from there. After you have your info organized you go to the second subcategory, labeling the information. The best way to do this is with keywords that a user might use in a search engine to find your page. Once you have everything labeled you go to the final step is setting up the navigation. Here you need to think about the order you want people to see the information and set it up accordingly.

2. Page/Screen Design
Layout is a very important aspect of effective communication. At the same time, there really are no set rules for designing the layout of a web page. But the book does give 3 guidelines
• Content - Provide more content than navigation on each page
• Identification - Include critical info and site identification near the top. The top left corner is also a natural focal point for Web and print pages.
• White Space - “Don’t fill every pixel of your page.” It helps guide a user’s eye around the page.

3. Content
Content is still key, pretty pages mean nothing if the content isn’t there. The book points out two aspects for good electronic content: effective writing and ensuring credibility. The book has a nice table (table 13.19) on p499 discussing some guidelines to building credibility. Also, some good writing tips from the book…
• Be Concise
• Keep text chunks short
• Use headings and bulleted lists
• Use Active Voice - identifier a doer for an action (ie you, me, us, etc…) It’s more engaging for the reader.
• Consider international readers, the world is bigger than little ol’ US
• Keep important info near the top followed by descriptions. Make important info easy to find when scanning.
• Limit ‘in-text links’ and provide descriptions so the user knows what to expect if they click this link

Standards & Tools
Standards are important because it allows a massive system, like the web and all PCs connected to it, to function consistently. Table 13.20 on p501 has a nice list of tags, scripts, and programming tools used in web page design.

Iterative Design Process
The first step to any project is defining is the project’s purpose and scope. The second step to any project is developing a project plan, this plan is an outline of the resources and time needed to complete the project. It’s also very important to maintain documentation of maintenance and updates to keep things consistent. Figure 13.21 provides some good questions to think about when planning a project, some of it is web page specific but the development and project management sections could be applied to any project.

When developing a web page, start by analyzing similar web pages and the book even provides a nice assessment sheet on p506, Figure 13.22. After you have some ideas on what you want, create a prototype and run the same assessment. Keep the project and process coordinated, communication is key to keeping the project on track and all elements consistent.

Make information and features accessible. Provide alternative representations of information, use alternative tagging, and add transcripts or captions to audio information. While this may not be everything, just always keep in mind to keep your information accessible to as many people as possible.

Chapter 14 - Creating Definitions

Defining significant terms using vocab and other ways understandable to the audience is necessary in creating technical documents, oral presentations, and visuals. Failure to provide adequate definitions may lead to the audience getting confused by multiple meanings, complexity of meanings, technical jargon, and symbols.

Recognizing and answering questions the audience may come up with beforehand, is a way to make effective definitions. After first asking "What is it?" you can ask simple questions such as:

Physical Characteristics *What does it look like?
*What are its physical features?
Comparison *How is it classified?
*What is it similar to?
*How is it different from similar objects?
Whole/Parts *Ware are its distinguishing characteristics?
*What are it components?
Function *What does it do?
*How does it work?
Operation *Who uses it?
*What are examples of its use?
*What is its value?

These questions may be answered by constructing formal, informal, operational, or expanded definitions.

Formal Definitions
Formal definitions are definitions you'll find in a dictionary. Sometimes definitions may not exist for new products and processes or may not be adequate for old ones. In that case you need to construct a new formal definition in which the format is always species equals genus plus differentia. The species is the term that is defined. Genus is the class or category to which it belongs and differentia is the distinguishing characteristics that differentiate the species from others in the same genus.

Informal Definitions
Informal definitions are often times used by communicators without even realizing it. Six types of informal definitions commonly used are:

*Synonym - A Word that basically means the same thing as the original term
*Antonym - A word that means the opposite to the original term.
*Negative - A definition that gives an explanation of what something is not.
*Stipulation - A definition that gives the meaning of a term for a particular situation or application.
*Analogy - Is a comparison of the unfamiliar to the familiar to find the major characteristics of the unfamiliar term.
*Illustration - Is a diagram or drawing to illustrate a term.

Operational Definitions
Operational definitions give significant steps in a process to make it clear or to measure it. The meaning of operational definition is different in different technical fields.

Expanded Definitions
Expanded definitions explain and clear up info. They help maintain audience interest and can adapt types of technical communication for wider audiences. The forms of expanded definitions most used are etymology, history, and examples.

Lastly, the technical communicator must decide where to put the definitions. The possibilities for placing definitions include: a glossary, information notes and sidebars, incorporated info, appendixes, and in online help. They should be placed in one of the aforementioned areas that would be most convenient for audiences.

Chapter 11 - Designing Information

The goal of this chapter was to describe principles that affect accessibility, comprehensibility, and usability of your documents when technical information is presented.

There are two major designs to be concerned about when you present information to your audience.

1. Information Design - This is concerned with the way you organize your information to increase audience comprehension.
2. Document Design - This is a part of information design and consists of five main elements in technical writings.

There are five main elements in technical writings:

1. Textual Elements - letters, numbers, and symbols.
2. Spatial Elements - the spaces between the elements as well as the placement of textual and graphic elements.
3. Graphic Elements - punctuation marks, typographic devices, geometric forms, and visual diagrams.
4. Color and Textural Elements - the hue, saturation, brightness, texture, etc.
5. Dynamic Elements - the motion that is implied in a print document. Often actual motion in an electronic document that uses various kinds of animation.

When applying these elements, it is important to remember that people typically do not like to read extended reports. It is best to make the document as little as possible.

There are three major things that can be done to enhance these technical and electronic documents:
1. Chunking and labeling information by effective use of white space and headings.

2. Arranging information by appropriate integration of visual and verbal chunks.

3. Emphasizing information by effective use of typographic devices and typefaces.

Chunking and Labeling Information

Information can be grouped in chunks using two factors
1. Logical topical relationships
2. Audience needs for the information

A very good example of information grouping or chunking based on topical relationships is table of contents we see everyday in websites and books.

• Different ways to chunk information into groups are by using white space, margins, alignnment and leading and line length. White spaces (on paper or electronically) may be used based on the needs of the document, but they are usually used for margins, between lines within a paragraph, between paragraphs and sections of a document, and around visuals.
• Similarly, carefully choosing margins is equally important, to make the document readable and attractive, i.e. not making the margins too wide or too narrow.
• Another important factor that makes a document accesible and legible is alignment. Proper alignment and justification (right, left, full etc) give a document neta and clean appearance. Also, though it seems like fully justified text would be a better way to justify documents, research shows that managers and nonmanagers prefer dcouments with ragged-right margins because the spacing between each words are even.
• Another way of chunking information is the use of spacing between lines. Generally, text that has line spacing that is one and a half times the letter height is considered easiest to read. Also the lenght of the line and the font type and size really determine the readability of the text as well.

Headings to Label Chunked Information

These are useful for grouping specific portions of information into a bundle that is easily identifiable by the reader. Therefore, if he would wish to find something, he can easily find what he is looking for.

Using Design Conventions

There are two main practices that will help produce more effective documents:

1. Selection of Appropriate Grids.
2. Placement of Visuals Near Related Text

This is useful for being able to show how various things apply in a specific text. For example, putting a specific picture relating to some texts right by the text is much more efficient than placing it in an appendix.

Avoiding Problems in Arranging Information

There are four potential problems that distract readers:

1. Chartjunk (miscellaneous graphic junk that does nothing to help people understand the information)
2. Tombstoning (involves aligning headings so that readers mistakenly chunk the text when they look at the page)
3. Heading Placement (comes from leaving too few lines after a heading or a subheading at the top or bottom of a column or page)
4. Widows and Orphans (Widows are leftover words and Orphans are when a column or page break occurs in a paragraph after the first line of the paragraph)

Emphasizing Information.
After chunking, labelling and arranging information you may still need to emphasize selected portions of the text to make more important information more accessible and comprehensible. And even though, in today's electronic document's day and age, readers may override a designer's choice to formatting a document, one should still consider typeface and typographic devices important tools to emphasize certain texts for both print and Web pages.

Typefaces

Typefaces or fonts are very important in determining the user's attitude and reaction to a document and so they must be chosen wisely depending upon the intended audiences.

• There are different types of fonts. The most common differentiation in type faces are the serif types and sans serif types. The serif fonts have tiny fine lines usually at the top or bottom of letters, while sans serif types are plain fonts without such lines. Both type of font faces have various uses. For example, sans serif type faces are usually used for short documents, documents for children, the elderly people and people with visual impairments or disabilities because they are simpler and the letters don't have as many distinguishing features. Similarly, long documents like technical reports and journals that are to be read by all readers, usually use serif typefaces so that readers don't tire too quickly. A document with different types of contents can use different kinds of fonts for differentiating such different contents. For example in a manual, commands, instructions, names of components etc are differentiated by using differentiated font faces.
• Choosing the correct type size or font size is also very critical in creating documents. Very small font sizes could result in readability issues, while very large font sizes could offend adults, because big font sizes are usually associated with children's books. The font size should be chosen appropriately depending upon the type of document (eg. business documents, powerpoint presentation etc), intended audience (eg. children, home users, business partnerts etc), attention desired (eg. warnings, special messages etc). Also font size should be chosen based on font face because, the same font size of different font faces could be different in actual sizes. Also, one should be careful when choosing font for web pages, as the same font face and size look different on Windows based computers compared to Macintosh computers.
• The style of font or type you use can also influence the audience. Using ALL CAPS can be effective when it is used to emphasize certain headings, warnings etc, but typing a long sentence in ALL CAPS generally reduces the speed the user can read it and thus he or she may lose interest. A general guideline to writing a document is to use no more than two typefaces and a total of four variations of typeface, type size, or style on a single page or screen, unless otherwise required, for example in a manual.

Typographic Devices

Numbered Lists are common elements in sets of instructions and are also used in reports and proposals

The reasons they are so important are:

1. Sequence or chronology of items
2. Priority of items
3. Total count of items

Using italics, underlining, color and boxes also has three important uses as well

1. Identify Text Hierarchy – Will help the readers locate the main sections in a text
2. Chunk Information – Can effectively chunk related information for readers
3. Emphasize Key Points – Can also be used to highlight terms and points within the text.

Chapter 10

Nick Annoni and Andy Theirl

This chapter talks about the importance of properly organizing your information so that is clear for your audience to understand. This is the most important part of communication because if the information isn’t organized well, you can easily loose the purpose of the message. When audience perceives information that is unclear, they can change the meaning of the message by attempting to translate the information. When that happens, they can take the message in a negative way or just a way that makes no sense to them at all. Some of the tools in organizing the information are to use visual aids for the audience to get a better understanding of the information.

Three main strategies in organizing information:

• Outlines
• Storyboards
• Tables

Outlines are very good to use when you are trying to organize a large amount of information. You may have pages of information but don’t know where to start with it when you are doing a research paper. That is why you use an outline. You start out with using some valuable information and grouping it together on the outline. Then from there you can revise it as many times as you want. You can move information around so that it makes more sense and is clearer to you and your audience.

A storyboard is also a useful tool in presentations. It is simply just a way to tell a story but relevant to your information. They often involve pictures and text on them and are presented in order so that it can show a process. It is more and more done on computer now instead of paper sketches. PowerPoint can be used for it and web sites with links also work as story boards. A storyboard can help you keep your information organized and easy to interpret if you are the audience.

Tables and spreadsheets can be useful when you are comparing two different situations. You can also use them to display statistics. Tables are very much necessary when you have numbers involved in you information.

There are many different ways to order your information such as alphabetic order, numerical order and continuums. These are all very common in everything we do because it simplifies the information.

When looking for information online it can be sometimes challenging. It is sometimes worse when a website is poorly organized and can actually cause the business to lose money because people will give up on there search.

There are more types of organization that are important to use when you are trying to make the information more clear. You can chronologically order the information which is just organizing the information based on the occurrence of information. Spatial organization is where you organize something based on what it is nearby in the process. Ascending to descending order is when you order the information from most important to least important information. Cause and effect is as simple as it sounds, talk about the cause of an instance that happened. From there you can analyze and make an important factor in your research. You may have more then one cause to an effect but the purpose of the research is to decide what the true cause is.

Chapter 9- Ensuring Usability

By: Ryan & Andrea

This chapter talks about what usability actually is, critical principles that guide it, testing usability, the different kinds of testing, differences in those that use it, how to implement a test plan, conducting and reporting the tests, and the accessibility aspect of usability.


The chapter starts out talking about how different documents may be hard to comprehend and can make the experience frustrating, which would be poor usability. To be usable the communication needs to successfully meet the needs of the people that are using documents, websites or other media in difficult situations. This is why usability is important.




Usability is the degree in which texts easily and effectively enable people to accomplish their goals. There are five principles that are very important and need to be applied to visuals, presentations, print and electronic texts. These principles can be used to assess the usability to different kinds of texts developed by technical communicators and technical professionals. They are:
Learnability- How easily people learn to use the text and how quickly they can
become productive using them?
Efficiency- How productive people are while using the text or product?
Memorability- How well do people remember how to use the text or products
from one use to another?
Error Recovery- How many errors and how serious are those errors that the users
make? How quickly can the users correct those errors?
Satisfaction- How satisfied are the users with the product’s performance and do
they enjoy using them?

Usability testing is very important in usability principles. Usability testing gathers information from people that are similar to the intended users. They are observed while using the products and texts, which measures the five principles, learnability, efficiency, memorability, error recovery, and user satisfaction. The purpose of usability testing is to identify problems before the text is released and also for historical records of the test results, which is helpful for future documents or development of additional materials. The testing provides information in ways in which people think, believe, feel and perform, the four areas are:

Cognitive: How users think about the test?
Perception: How the users understand the text?
Affect: What the users’ attitudes are towards the test?
Performance and behavior: What do users do with the text and products, how do
they try to solve the problems and what do they do
when they are faced with a problem?

There are limitations when designing a test and some things that a person needs to consider is who is participating in the test and what kind of attitudes they have will have an affect on the end result. The testing situation is something else to consider, the tests need to be designed to reflect different situations in which communication will be used. The technique of the test, different stages require different procedures, so design appropriate testing for each stage of development. Last, the testing procedures can have an affect on the end result. Even though testing takes time, it increases the chances that serious usability problems will be avoided.

There are three types of testing, text-based, expert-based, and user-based. Text-based tests are a range of local-level language, visual and design features. Conclusions are drawn from this and changes are done to improve the text’s accessibility and comprehensibility. Expert-based testing is useful for assessing technical accuracy and supporting evidence for the intended audience. It uses technical reviews by subject-matter experts, substantive editorial reviews and design reviews. User-based testing obtains information directly from users, which is more sufficient then text-based testing and expert-based testing.


Information that is collected from users as they read and use a text is called concurrent testing. It involves watching users’ behaviors as they perform a task. Another kind of concurrent testing is having users read and think aloud. This shows specific areas that are confusing or tasks that are difficult for users. Retrospective testing is information collected from users after they have finished using a text. Some methods are questionnaires, interviews, or focus groups.
There are 10 steps to consider before starting a testing process:
1. Goals- Come up with goals for your testing
2. Criticality- Decide what type of testing feedback you need
3. Constraints- Figure out constraints that you have to work with
4. Schedule- Build a time for testing into the schedule
5. Involvement- Make sure all key personnel understand the goals and cooperate
with the testing
6. Timing- Test products and texts are different points in development
7. Goodness of fit- Test procedures should be appropriate and relevant to the
goals
8. Ease of use- Test procedures must be easy for test participants to understand
9. Usable form- Manage the production of test data so usable results are
achieved
10. Updating- Test results will be used as part of the development and revision
process

You want to select users that fit the profile of your target audiences. Then you can implement the plan. This involves selecting test participants, developing test questions and introducing the rules and procedures to the participants. Then the test can be given. Once the test is finished you may review the results. Look at the amount of time it took the participants to complete tasks, or how many errors took place during certain tasks, or how often different test participants note the same usability issues.

Ensuring Accessibility

Accessibility is an important aspect of usability which focuses on providing access to information, especially to people who have disabilities. Technical communicators and professionals should promote information for all people. They need to consider the differences in users’ vision, hearing, cognition, and also take into consideration their economic, educational and physical environments. Seven principles that were developed for accessibility are:
Equitable use- design is useful to people with diverse abilities
Flexibility- Accommodates a wide range of individual preference and abilities
Simple and intuitive- Design is easy to understand
Perceptible information- Communication necessary information effectively to
users, regardless of condition or sensory abilities
Tolerance for error- Design minimizes hazards or unintended actions that may
occur
Low physical effort- Design can be used efficiently and comfortably with
minimum fatigue
Size and Space for approach- Appropriate size and space are provided, regardless
of user’s body size, posture or mobility

Lastly, accessibility often refers to American with Disabilities Act. So, this requires technology information of federal agencies, vendors, or contractors to have accessibility for people with disabilities, including their own employees.