Study Guide
Lecture 5 Technical Writing Applications
-
University:
Kentucky State University -
Course:
ENG 216 | Technical Writing Academic year:
2020
-
Views:
436
Pages:
79
Author:
Apolenajz
Lecture 5: Technical Writing
Applications Application 1:
How To Write Memorandums (Memos)
Memos are the everyday “workhorses” for
transferring information from one person
to another.
In terms of how frequently memos are
used in the computer industry, they are
the most important type of documentation
you are likely to write. Memos
Memos may vary from extremely informal
handwritten notes to formal, typed interoffice
memorandums (IOMs), they may include
electronic mail and on-screen messages.
Memos should be as concise and direct as
possible. That does not, however, stipulate
(require) optimum (best) length for memos. Some
formal IOMs can run as long as (10-20) pages,
including attachments. Memos
Memos can be organized as follows:
Summary
Discussion
Conclusions
Requests of Recommendations
(Optional)
Graphics
as needed Memos
Types of Memo According to their purpose
1- Recommendation Memos
(either requested or self initiated)
2- Informative Memos
3- Information Requested Memos Types of Memo :
1. Recommendation Memos
If the reader requested an investigation that
will lead to conclusions and
recommendations. The memo generally
adheres to the following design: Types of Memo :
1. Recommendation Memos
Reader requested Memo
Introduction
Discussion
Problem
summarization
as the writer
understands it.
Presents an
evaluation of all
alternatives the
writer
considered.
(including the
Pros and Cons
of each)
Conclusion and
Recommendation
-recommends a solution.
-Analyzes it.
- Discuss important
element of implementing
it. Types of Memo :
1. Recommendation Memos
Writer initiated Memo
(Feeling that the intended reader has a need for the information presented)
Introduction
Discussion
-Supplies background
orientation to the issue
being reported on.
Presents an
evaluation of all
alternatives the
writer
considered.
(including the
Pros and Cons
of each)
-Definition of the
specific problem at
hand.
-A brief statement of the
recommended solution.
Conclusion and
Recommendation
-recommends a solution.
-A full analysis of it.
- The presentation of
important aspects of
implementing it. Types of Memo :
2. Informative Memos
These memos are issued at the discretion
(good judgment) of the writer to provide
readers with information they “need to
know”.
Informative memos are usually short, to
the point, and often informal.
Even so, for them to work, they should be
well organized. Types of Memo :
2. Informative Memos
Informative Memo Organization
Introduction
Discussion
Request
-Orients the reader to the
subject of the memo.
-Brief description of the
contents of the memo.
-Suggests the action the
reader should take with
regard to the information
presented in the memo.
The
presentation
of the
information
An optional section
used when the writer
wishes information from
the reader pertaining to
the contents of the memo Types of Memo :
3. Information-Requesting Memos
These memos are issued when the reader
has identified a “need” for specific
information. Usually, they are too short.
The following design makes it likely that
the reader will notice the request easily: Types of Memo :
3. Information-Requesting Memos
Information requesting Organization
Introduction
Discussion
-An orientation to the
reader’s needs.
- Reasons why the
memo was written.
- Why it was sent to
the reader.
A direct
request for the
information
needed. Memo Format:
Memorandum
Date:
To:
From:
Subject:
Text of the memo
The text in this area should be concise, clear, and
well-written. Organization is very important. If you
have more than one topic or subject (or you have
subtopics),
you can use headings to make your
message more readable and understandable. If you
have a list of items within your memo, use bullets.
Bullets, like headings, are frequently used in memos
to make them easier to read. Avoid unnecessary
topics or information--and don't repeat yourself.
Some memos contain conclusions; some omit
them. Conclusions are good to use if you have
several points to make and wish to summarize them
or make a recommendation. Conclusions are also
useful if you wish to make a request.
Notification of attachments is included at the very
end of the memo, right above the bottom margin and
against the left margin.
Always identify your attachment in the following
way--Attachment: Exhibit I. Some points to remember about good
memo writing are as follows:
Be kind to your reader--use headings and
bullets as necessary to make the memo easy
to read and key points stand out.
Be concise--long sentences with complex
construction do not belong in memos.
Keep memos short and to-the-point.
Remember memo format
Identify your attachments--if your attachments
become separated from the memo, your reader
will know that they were supposed to be there
and can ask for them.
Be coherent (logical)--limit each paragraph to
only one idea. Keep your sentences flowing
smoothly, and keep them short.
Use the first person (I or we); use short, simple
words; be as informal as the situation allows;
use concrete, specific words.
Proofread your work--always read your work (or
have someone else read it) before you sent it out.
Identify your audience--identify the person or
persons to whom you are writing. Think about what
they know, who they are, what they want to see or
hear, how they are situated. Clarify your audience's
background, context, and environment. Never,
never , never write without identifying your
audience first. Application 2:
Feasibility Reports
A feasibility study analyzes the problem
and its implications, evaluates alternative
solutions, and (usually) recommends a
particular course of action. The results of
such a study are written up in a feasibility
report. Application 2:
Feasibility Reports
Feasibility has two somewhat different
meanings:
1- Technical Feasibility
2-Suitability or reasonability 1. Technical Feasibility
It means technically capable of being
done, Executed, or effected. 2. Suitability or reasonability
1.
2.
3.
4.
5.
In this larger sense, the notion of feasibility covers five general
criteria that are used to evaluate any proposed solution to a
problem:
Effectiveness: Is the solution effective? Will it solve the
problem posed?
Technical Feasibility: Can the solution be implemented? Does it
require technology or resources that are unavailable?
Desirability: Would we want to implement the proposed
solution? Does it have any undesirable effects? Does it have
desirable effects?
Affordability: What will the solution cost to implement? To
maintain? Is this cost reasonable?
Preferability: Is the solution better than or preferred over any
other possible solution? Why? Application 2:
Feasibility Reports
This larger notion of feasibility also covers any
special criteria necessary or appropriate to the
given situation, for instance, important issues of
safety, environmental pollution, conformity to
particular laws or traditions, precedent
(standard) setting, or justice. As technical
(expert) writer, you must be able to deal with all
the relevant issues and criteria in a feasibility
study.
When all these criteria enter into the notion of
feasibility, they provide the basis for a
(complete)full-fledged argument of fact or policy. Application 2:
Feasibility Reports
For instance, when you judge an alternative
(Software) as being effective, technically
feasible, desirable (including safety), affordable,
and preferable, and then argue on the basis of
these judgments that the alternative is feasible,
you have constructed an argument of fact
supported by several sub arguments of fact as
discussed above. If you go one step further and
argue that the alternative (Software) should be
developed, you have constructed an argument of
policy supported by several sub arguments of
fact, one of which is the argument of feasibility. Application 2:
Feasibility Reports
The feasibility report is much like other
kinds of technical reports: it is based on a
problem; it presents an analysis of one or
more possible solutions; and, if possible,
it recommends the best solution given the
circumstances involved. Feasibility report
structure can be outlined as follows: - Application 2:
Feasibility Reports
1.Foreword
This section describes the general situation related to a
particular problem, and should be written for all readers,
especially managerial and no specialist readers.
2.Summary
This section summarizes the evaluation of each alternative
according to effectiveness, technical feasibility,
desirability, affordability, and preferability. As a result of
this study, one alternative should be recommended. Once
again, this section should be written for all readers,
especially managerial and nontechnical readers. Application 2:
Feasibility Reports
3.Details: This section presents the essential supporting details
and arguments for technical or specialist readers, and covers the
following subsections: 3.1 The problem and its background
3.2 Argument for the recommended alternative
3.2.1Criteria for judgment
3.2.2The selected alternative as the recommended solution.
3.2.3Rejection of alternatives
3.3 Development and Implementation of the selected alternative.
3.3.1 Brief explanation of the technique.
3.3.2 Cost and time required.
3.4 Conclusions and recommendations
3.5 References
3.6 Appendixes: This section can be used to include nonessential but
supporting information or disruptively long information. Application 3: Proposals
How to Write Proposals
Strictly speaking, a proposal is a: Sales piece of writing,
Communication designed to obtain work,
Go-ahead on a project, and so on. Proposals
Proposal ultimate goal is to identify a
need on the part of the audience and
outline ways that the writer, or the group
of people the writer represents, can
satisfy that need.
Writer(s) Identify Need(s)
Outline ways Solution Proposals
For proposals to be successful:
writers must convince the audience that
they can do something for the audience,
that it needs to be done, and that the
writers or proposing group can expect
some sort of recompense (reward) for
having done it. Proposals
As it appears, this is not an easy task.
Accordingly, you should try to do some, if
not all, of the following: 1- Consider the needs and level of
understanding of the audience (i.e.,
analyze your audience).
2- Use a simple format. Proposals
3- Make sure that the final draft is clear and
legible/readable (good letter quality print,
attractive layout).
4- Keep paragraphs and sentences
reasonably short (shorter in proposals
than in analysis reports, for example). Proposals
5- Use headings.
6- Use the active voice style whenever
possible. Proposals
Finally, writers should realize that:
“Readers read proposals in order to reject
them”.
You will want to provide: “Skimming (read quickly) cues for intuitive
readers, as well as sufficient details about
the project for sensing readers”. Proposals
Make it easy for people to judge your
proposal by supporting it with:
“Logical reasons (for thinking evaluators)
and with how it fits into their value
systems (corporate, national, etc,) for
feeling readers”. Application 4 : Progress Report
Progress reports are issued at
predetermined intervals during an
ongoing project.
Progress reports are used for one
purpose: to report the progress made on
a project during the interval covered by
the report. They can do this most
concisely when they adhere to the
following: Progress Report
Progress report Structure
Introduction
Discussion
Future Work
-An orientation to
the status of the
project by
describing:
An analysis of the
accomplishment
and problems
during the
interval being
reported on.
A statement of the work
planned for the next
interval.
1- background
2- What has been
Accomplished prior
to the present. Case Study (Progress Report):
The following table
shows the estimated
costs associated with
the required tasks to
accomplish a project:
Tasks
Estimated
Costs
Expected
Time
A (1-2) 10000
B (1-3) 30000
2
3
C (2-4) 3000
1
D (3-4) 6000
3
E (3-5) 20000
F (4-6) 10000
2
2
G (5-6) 8000
1
87000
Total Cost Case Study (Progress Report):
At the end of month
four you got the
following information
about the actual
implementation of the
project:
The Progress Report
will be:
Tasks
Actual
Costs
Percentage
of Execution
A
B
12000
30000
100%
100%
C
D
1000
2000
50%
33%
E
F
10000
0
25%
0
G
0
0
55000 Actual
Cost Case Study (Progress Report):
Tasks
Actual Costs
Estimated Cost =
(percentage of execution x
Total Estimated Cost)
Deviation = (Actual
Cost – Estimated
Cost)
A
B
12000
30000
10000
30000
2000
0
C
D
1000
2000
1500
1980
-500
20
E
F
10000
0
5000
0
5000
0
G
0
55000
0
48480
0
6520 ? Application 5 : User Manuals
A User Manual is a technical document
intended to give assistance to people
using a particular system.
It is usually written by a technical writer,
but can also be written by programmers,
product or project managers, or other
technical staff. User Manuals
User manuals are written for electronic
goods: computer hardware and software
Most user manuals contain both a written
guide and the associated images.
–
–
In the case of software manuals, it is usual to
include screenshots of how the program should
look
In the case of hardware manuals often include
clear, simplified drawings. User Manuals: Sections
The sections of a user manual often include:
–
–
–
–
–
–
–
–
–
A cover page
A title page and copyright page
A preface, containing details of related documents and
information on how to navigate the user guide
A contents page
A guide on how to use at least the main functions of the
system
A troubleshooting section detailing possible errors or
problems that may occur, along with how to fix them
A FAQ (Frequently Asked Questions)
Where to find further help, and contact details
A glossary and, for larger documents, an index User Manuals for Software
The user manual for software is almost as important as
the software itself.
Manuals are typically short, but if more detail is needed,
they can be much longer.
The length of a manual will depend solely on the type of
software and how much detail it must include.
Users will appreciate manuals with easy to find, concise
information, with enough detail to prevent confusion. Instruction to write a user manual for
a software
1.
Write an outline for the manual .
This will give you a plan to follow.
Things to include in the outline are the
installation procedure, software purpose, menu
descriptions, common tasks, advanced
functions, and a troubleshooting section.
Also include sub-sections in your outline for
specific tasks, such as creating a new file,
saving files, and printing files. Instruction to write a user manual for
a software
2.
Detail the installation process, including
computer requirements.
Provide requirements before the main
installation procedure so users can prepare their
computer.
Include even the most basic steps for computer
beginners. These steps may include "doubleclicking the installation file" or "insert the CD into
the CD-ROM drive“. Instruction to write a user manual for
a software
3.
Provide a detailed description of the software's
purpose.
–
–
Include what a user needs the software for and how they
can benefit. For instance, if the software deals with
accounting, explain common accounting tasks that the
software makes easier.
Include a brief description of advanced features that
makes this software different from others on the market.
For instance, your software may be able to generate more
reports or supports more file types than any other program
currently available. Instruction to write a user manual for
a software
3.
Provide a detailed description of the software's
purpose.
–
–
Include what a user needs the software for and how they
can benefit. For instance, if the software deals with
accounting, explain common accounting tasks that the
software makes easier.
Include a brief description of advanced features that
makes this software different from others on the market.
For instance, your software may be able to generate more
reports or supports more file types than any other program
currently available. Instruction to write a user manual for
a software
4.
Explain how to navigate menus.
5.
Write a separate section for advanced functions and
extra features .
6.
Explain each item in the menus provided.
This is the place to go into detail. For instance, a user manual for
Microsoft Excel might include information on creating reports,
links, and macros.
Provide troubleshooting tips.
Explain the meanings of any errors the user might encounter,
how to solve the issue, and how to prevent it in the future.
This is also the place to include contact and help desk
information. User Manuals
Writing a good user manual is not an easy job.
This requires you to have good experience in
technical writing, and be knowledgeable in the
subject about which you are going to write the
manual. User Manuals
To make it easy, follow the five steps in
your writing:
1- Supply a (real) manual.
An amazing number of companies
rationalize (reduce) their way out of
supplying a manual at all, and then
complain as loudly as anyone else about
the stupid users calling customer
support.
User Manuals
2 Explain the problem being solved
A lot of bad manuals are actually good feature specs
that companies have just translated from engineering
into a human language, and then shipped.
The problem with this approach is that you end up
with a manual that explains every feature in depth,
while keeping secret why anyone would ever want to
use them. User Manuals
Programming language manuals are almost
universal in this failing. They present 100 or 200
different commands without once mentioning what
they are useful for.
Explain a problem and offer a solution and people
will remember it forever.
Jump right to the solution, without ever presenting
the problem, and it just won't penetrate User Manuals
3 Present the concepts, not just the features.
Well-designed software should be centered on a few,
large concepts.
Any time you learn a new piece of software, you go
through the process of constructing a mental model
of the software, called the "User Model."
Building a model requires a framework, and the
framework consists of these large, key concepts.
Without a framework, it is extremely difficult to learn. User Manuals
That's why manuals written from specs are
usually impossible to learn from. The key
concepts are entirely absent, so the user
has nothing upon which to hang the bits
and pieces of knowledge offered. Instead,
they kind of float around in a cloud until the
poor reader finally sees the pattern. User Manuals
When a user does finally "get it," the bits and
pieces do not then suddenly come together;
Most of the bits and pieces, with nothing to hang
them on, will have drifted off forever. The user
must now re-read the entire manual, finally tying
the bits and pieces in place on their newfound
framework.
Manual writers will not themselves "get it"
either through lack of trying, lack of interest, or
serious lack of ability. These manuals are
useless. User Manuals
Manual writers must be introspective.
They must write the concept down and
present it early enough to their readers. User Manuals
4. Give more than they deserve
Manuals need to cover the task domain.
The depth and extent of the task domain
that must be presented will depend on a
number of factors, including the expected
domain knowledge of the users and the
amount of knowledge necessary for
people to be able to use the application. User Manuals
5 Make it enjoyable to read
To make it enjoyable to read, your writing should achieve
the following:
Continuity between sentences, paragraphs, and sections
of your manual on one hand, and between figures and
tables and the written text of the manual on the other.
Use transitional words to guide the readers through the
manual, but be careful do not overusing them.
Carefully choose the places at which you refer to figures
and tables Technical Writing: Applications
User Manual Application 1 : User Manuals
A User Manual is a technical document
intended to give assistance to people
using a particular system.
It is usually written by a technical writer,
but can also be written by programmers,
product or project managers, or other
technical staff. User Manuals
User manuals are written for electronic
goods: computer hardware and software
Most user manuals contain both a written
guide and the associated images.
–
–
In the case of software manuals, it is usual to
include screenshots of how the program should
look
In the case of hardware manuals often include
clear, simplified drawings. User Manuals: Sections
The sections of a user manual often include:
–
–
–
–
–
–
–
–
–
A cover page
A title page and copyright page
A preface, containing details of related documents and
information on how to navigate the user guide
A contents page
A guide on how to use at least the main functions of the
system
A troubleshooting section detailing possible errors or
problems that may occur, along with how to fix them
A FAQ (Frequently Asked Questions)
Where to find further help, and contact details
A glossary and, for larger documents, an index User Manuals for Software
The user manual for software is almost as important as
the software itself.
Manuals are typically short, but if more detail is needed,
they can be much longer.
The length of a manual will depend solely on the type of
software and how much detail it must include.
Users will appreciate manuals with easy to find, concise
information, with enough detail to prevent confusion. Instruction to write a user manual for
a software
1.
Write an outline for the manual .
This will give you a plan to follow.
Things to include in the outline are the
installation procedure, software purpose, menu
descriptions, common tasks, advanced
functions, and a troubleshooting section.
Also include sub-sections in your outline for
specific tasks, such as creating a new file,
saving files, and printing files. Instruction to write a user manual for
a software
2.
Detail the installation process, including
computer requirements.
Provide requirements before the main
installation procedure so users can prepare their
computer.
Include even the most basic steps for computer
beginners. These steps may include "doubleclicking the installation file" or "insert the CD into
the CD-ROM drive“. Instruction to write a user manual for
a software
3.
Provide a detailed description of the software's
purpose.
–
–
Include what a user needs the software for and how they
can benefit. For instance, if the software deals with
accounting, explain common accounting tasks that the
software makes easier.
Include a brief description of advanced features that
makes this software different from others on the market.
For instance, your software may be able to generate more
reports or supports more file types than any other program
currently available. Instruction to write a user manual for
a software
3.
Provide a detailed description of the software's
purpose.
–
–
Include what a user needs the software for and how they
can benefit. For instance, if the software deals with
accounting, explain common accounting tasks that the
software makes easier.
Include a brief description of advanced features that
makes this software different from others on the market.
For instance, your software may be able to generate more
reports or supports more file types than any other program
currently available. Instruction to write a user manual for
a software
4.
Explain how to navigate menus.
5.
Write a separate section for advanced functions and
extra features .
6.
Explain each item in the menus provided.
This is the place to go into detail. For instance, a user manual for
Microsoft Excel might include information on creating reports,
links, and macros.
Provide troubleshooting tips.
Explain the meanings of any errors the user might encounter,
how to solve the issue, and how to prevent it in the future.
This is also the place to include contact and help desk
information. User Manuals
Writing a good user manual is not an easy job.
This requires you to have good experience in
technical writing, and be knowledgeable in the
subject about which you are going to write the
manual. User Manuals
To make it easy, follow the five steps in
your writing:
1- Supply a (real) manual.
An amazing number of companies
rationalize (reduce) their way out of
supplying a manual at all, and then
complain as loudly as anyone else about
the stupid users calling customer
support.
User Manuals
2 Explain the problem being solved
A lot of bad manuals are actually good feature specs
that companies have just translated from engineering
into a human language, and then shipped.
The problem with this approach is that you end up
with a manual that explains every feature in depth,
while keeping secret why anyone would ever want to
use them. User Manuals
Programming language manuals are almost
universal in this failing. They present 100 or 200
different commands without once mentioning what
they are useful for.
Explain a problem and offer a solution and people
will remember it forever.
Jump right to the solution, without ever presenting
the problem, and it just won't penetrate User Manuals
3 Present the concepts, not just the features.
Well-designed software should be centered on a few,
large concepts.
Any time you learn a new piece of software, you go
through the process of constructing a mental model
of the software, called the "User Model."
Building a model requires a framework, and the
framework consists of these large, key concepts.
Without a framework, it is extremely difficult to learn. User Manuals
That's why manuals written from specs are
usually impossible to learn from. The key
concepts are entirely absent, so the user
has nothing upon which to hang the bits
and pieces of knowledge offered. Instead,
they kind of float around in a cloud until the
poor reader finally sees the pattern. User Manuals
When a user does finally "get it," the bits and
pieces do not then suddenly come together;
Most of the bits and pieces, with nothing to hang
them on, will have drifted off forever. The user
must now re-read the entire manual, finally tying
the bits and pieces in place on their newfound
framework.
Manual writers will not themselves "get it"
either through lack of trying, lack of interest, or
serious lack of ability. These manuals are
useless. User Manuals
Manual writers must be introspective.
They must write the concept down and
present it early enough to their readers. User Manuals
4. Give more than they deserve
Manuals need to cover the task domain.
The depth and extent of the task domain
that must be presented will depend on a
number of factors, including the expected
domain knowledge of the users and the
amount of knowledge necessary for
people to be able to use the application. User Manuals
5 Make it enjoyable to read
To make it enjoyable to read, your writing should achieve
the following:
Continuity between sentences, paragraphs, and sections
of your manual on one hand, and between figures and
tables and the written text of the manual on the other.
Use transitional words to guide the readers through the
manual, but be careful do not overusing them.
Carefully choose the places at which you refer to figures
and tables
Lecture 5 Technical Writing Applications
of 79
Report
Tell us what’s wrong with it:
Thanks, got it!
We will moderate it soon!
Free up your schedule!
Our EduBirdie Experts Are Here for You 24/7! Just fill out a form and let us know how we can assist you.
Take 5 seconds to unlock
Enter your email below and get instant access to your document