Technical Communication
Writing at Work
1. Requires acute awareness of security and legal liability.
2. Requires awareness that documents may be read by unknown readers, inside and outside
the organization, for an infinite time.
3. Achieves job goals.
4. Addresses a variety of readers who have different perspectives from those of the writer.
5. Requires a variety of readers from those of the writer.
The Foundations of Effective Writing at Work
1.
2.
3.
4.
5.
6.
Planning the document
Determining content
Arranging ideas
Drafting
Revising
Editing
The Qualities of Good Technical Writing
1.
2.
3.
4.
5.
6.
Accuracy
Clarity
Conciseness
Readability
Usability
Correctness
Writing Ethically
Your Professional Obligations
➢
➢
➢
➢
➢
➢
To yourself
To your discipline and profession
To your academic institution
To your employer
To your colleagues
To the public
CODES OF CONDUCT AND STANDARDS OF PRACTICE
Ethical Principles
1. Legality- observe the laws and regulations governing our profession
-ensure that all the terms are consistent with laws and regulations locally and globally
2. Confidentiality- disclose business-sensitive information only with consent or when
legally required to do so
3. Honesty- seek to promote the public good in our activities / provide truthful and accurate
communications
- Before using another person’s work, we obtain permission
- We do not perform work outside our job scope during hours compensated by clients
or employers, except with permission; nor do we use their facilities without their
approval.
4. Quality- to produce excellence in our communication products
- Negotiate realistic agreements with clients and employers on schedules during project
planning.
5. Fairness- we respect cultural variety and other aspects of diversity in our clients
- Avoid conflicts of interest in fulfilling professional responsibilities and activities
6. Professionalism – evaluate communication products and services constructively and
tactfully
- Assist other persons in our profession through mentoring, networking and instruction
Recognizing Unethical Communication
➢
➢
➢
➢
➢
➢
Plagiarism and theft on intellectual property
Deliberately imprecise or ambiguous language
Manipulation of numerical information
Use of misleading illustrations
Promotion of prejudice
Unethical use of information
6 Forms of Unethical Communication
1.
2.
3.
4.
5.
Destructive- use of self-harm or speaking to a person in a harmful way
Coercive- use of physical force during conversation to compel a person to do something
Deceptive- the intentional transmission of information
Intrusive- the use of surveillance, such as hidden cameras
Secretive- the approach used to produce a silent reaction to sweeping indiscretions under
the rug
6. Manipulative- the type of communication used when trying get something is untrue by
lying
How to Avoid Unethical Communication
➢
➢
➢
➢
➢
➢
Establish straightforward guidelines
Promote knowledge
Provide tools
Be proactive
Employ data monitoring
Foster ethical behavior
Technical Writing Documents and Elements
➢ Instructions- a set of directions; provides a specific detailed step
➢ Procedures- provide a general guideline for performing a task
➢ Policies- rules that govern action
➢
➢
➢
➢
➢
➢
➢
Types of Instruction and Procedures
User manual
Reference manual
Tutorial
Quick reference guide
Online documentation
Procedure guide
Policies
➢
➢
➢
➢
Planning Instructions and Procedures
Who are the readers? What do your readers know about the subject?
What is your purpose?
What is the context in which the instructions/ procedures will be used?
Will the instructions be available online or on paper?
Structure and Organization
Introduction
➢ Familiarize the readers with the task to be performed
➢ The instructions will allow readers to do and what skill level the person should have to
perform
Theory governing the procedure or instruction
➢ Knowledge of the process may help readers understand
Warnings, cautions, hazards, and notes regarding safety or quality
➢ Any level of hazard needs to be described
Conditions under which the task should be performed
➢ Some instructions may require you to describe the physical conditions required to
perform a task
Name of each step
➢
➢
➢
➢
Place instructions in chronological order
Number of each step
Limit each instruction to one action
Include warnings whenever necessary
Guidelines
Organize the information in sequential steps
Hard copy vs. online
Provide clear signposts and goals.
Provide a list of all the tools or equipment needed to perform a task.
Make sure instructions and explanations are separate.
Organize similar material consistently.
Separate user actions from system reactions.
Instructions, Procedures, and Policies
Instructions- set of directions
-
Provides specific detailed steps
Procedures- provide general guideline for performing a task
-
A sequence of steps that tells the staff how to put policy into practice
Policies- agreed-upon rules that govern or constrain the operations so that employees behave in
a way that reflects the company/s mission and vision
Types of Instructions and Procedures
➢ User manual – step-by-step guide for how to operate something
➢ Reference manual- a storehouse of information about a product
➢ Tutorial- mini lessons on how to perform specifications
➢
➢
➢
➢
Quick reference guide- brief reminders of how to operate or use a product
Online documentation- on-screen help
Procedures guide- set of company or laboratory standard procedures
Policies-overarching guidelines for conducting
Components of Instructions and Procedures
1. Title- place on the cover of the document and then repeated on an inside title page
2. Legal information- contains copyright information, revision or edition numbers
3. Table of Contents- shows the user how the manual is organized and gives chapter, section
and page numbers.
4. List of tools, materials or equipment- placed at the beginning of the document which
alerts the user to have on hand
5. Explanations- gives the ‘nice to know’ information that creates a context for the steps
6. Hazard messages- warnings, notes, cautions should be placed prominently in the text
7. Troubleshooting- section at the end of the document devoted to fixing problems
8. Index- placed at the back of manual so that users can find information quickly
9. Purpose- often expressed as a title or a heading
10. Guideline- discusses the policy itself
11. Rationale- gives a few sentences of explanation about why such policy
12. Approval- indicates what authority has approved the policy
13. Date- the date when the policy was updated so that users can determine if they are using
the most current version
Planning and Researching
➢ Determine your purpose.
➢ Analyze your audience.
Organizing
➢ Must be task-oriented (follows the order of discrete tasks)
➢ Must be clearly formatted (page design should enhance usability)
➢ Must be transparent (should not be a barrier between the user and the job the user wants
to get done)
Designing
➢
➢
➢
➢
➢
Clearly label figures.
Be consistent with formats.
Decision tables.
Modular design
Information mapping
Editing
➢ Collaborate
➢ Achieve the right tone and style.
Testing for Usability
Types of Usability Tests
1. Written Tests
➢ Can be any traditional types of written examinations; multiple choice, matching,
completion, or true or false
2. Task-oriented Tests
➢ It determines how well users can follow the instructions to complete specific tasks
3. Additional Questionnaires
➢ Determines how the users feel about the documentation
4. Informal Observation and Interviews
➢ It yields more qualitative than quantitative
For International Communications
➢
➢
➢
➢
➢
➢
➢
➢
International English
Fit Local Standards
Do a Usability Tests
Balance Theory and Practice
Use Graphics and Icons Appropriately
Use color thoughtfully
Understand reading patterns
Use Local Number Representations
Technical Reports
Kind of Reports
1.
2.
3.
4.
5.
6.
7.
Recommendation report
Feasibility report
Progress report or status report
Trip report
Personnel report
Evaluation report
Economic justification report
Report Categories
Informal Report Heading
➢
➢
➢
➢
➢
Date
To
From
Subject line- states clearly and concisely the content of the report
Reference- links your report to previous documents such as company policies, legal
issues
➢ Action Required- states what action you want your readers to do
➢ Distribution list- indicates who will receive copies as well as the report’s file name
Parts of an Informal Technical Report
1.
2.
3.
4.
5.
6.
Introduction- report purpose, background or rationale, report development
Summary
Discussion
Conclusion
Recommendations
Attachments
Elements of Formal Reports
1. Prefatory elements
A. Letter of transmittal or memo of transmittal (addressed to the individuals who
will initially receive the report)
Should have the ff. info:
• Statement of transmittal
• Reason for the report
• Background material
• Mention of earlier reports
• Significant information relevant to the readers
• Specific conclusions and recos
• Financial implications
• Acknowledgements
B. Title page (provides critical identifying matter and may contain a number of
identifying items to distinguish the report)
The ff. often appears:
•
•
•
•
•
•
•
•
•
•
Name of the company or individual preparing the report
Name of the company or course which the report was prepared
Title & subtitle of the report
Date of submission
Code number of the report
Contract numbers which the work was performed
Company or agency logo
Proprietary and security notices
Names of contact
Descriptive abstract
C. Submission page
• Includes the list of contributors
• Emphasize the point made
D. Table of contents
• Indicates the page that serve as locating device for readers
• Forecasts the extent and nature of the topical coverage and suggests the logic
of the arrangement
• Reflects rhetorical purpose of the report
E. List of illustrations
• Usually divided into tables and figures but specific type like maps, financial
statements, photographs, charts and computer programs
F. Glossary and list of symbols
• List of abbreviations, acronyms, symbols and terms not known to readers
2. Abstract and Summaries
A.
-
Informative abstract
includes research objectives/methods/principal results and conclusions
from 50-500 words
help readers if they want to access the entire report
B.
-
Descriptive abstract
Contains the full report
Cannot serve as the report itself
Begins with the report purpose and explains content areas
C. Executive Summary/ Abstract
- Provide extensive development to provide decision makers the info they need without
reading the full report
3. Discussion or Body of the Report -(contains the information to be reported/explains in
detail /supports all conclusions and recos/ always includes report subject, purpose and
plan for development)
4. Collecting and Grouping Information
- Group material and notes into specific categories
- Plan the discussion around each topic
- Some kinds of reports have standard arrangement patterns
- Ideas should be presented in logical and inclusive arrangement
- Ideas may be presented to argue for specific point or position
5. Conclusions- statement of primary issues covered in the discussion
- provides judgement about subject
Factual Summary- covers the essential facts without interpretation
6. Recommendations – emerge from conclusions
- Proposed actions to be taken based on conclusions
7. References
8. Appendices- include documents that support or add to information in the discussion
• Letter reports
• Report checklist
*planning
*revision