E Technical Writing Pp3

Technical Writing Skills
Author: Hung H. Le, CEO

Date: 09-Aug-2007
Duration: 3 Hours
Danang 31-Jul-2007 Enclave®

Engineering Success
Contents It’s all about writings…
Objectives
Documents
Before Start
Styles
Mechanics
Contents
Mathematics
Reports
 Session Objectives
Abstracts
Tips
 Definitions – Technical Communication, Technical Writing, Technical Writer
Summary and Technical Documents
References
 Technical Documents – Process Documents and Product Documents
 Before You Start Writing – A simple checklist that stresses the importance
of knowing your objective and audience
 Using plain English – Style – The heart of the document because it
explains how to write in the simplest and most effective way
 Using plain English – the Mechanics – Covers vocabulary, spelling and
punctuation
 Writing Mathematics – Contains some simple rules you should follow if
your writing includes mathematical symbols or formulas
 Basic Structure for Reports – Explains how to organize your report into
sections and how to lay it out
 Abstracts and Executive Summaries – Explains the difference between
informative and descriptive abstracts. It tells you why you should always use
informative abstracts and how to write them
 Useful Tips on Technical Writing

Engineering Success
Contents What you need to improve your writing…
Objectives
Documents
Before Start
Styles
Mechanics Session Objectives
Mathematics
Reports
Abstracts
 To understand basic definitions, characteristics and concepts in
Tips
Summary
technical writing
References  To distinguish technical writing and general writing
 To understand needs of audience of technical writing
 To help engineers to write technical documents effectively
 To show that there is a better way to write using simple, plain
English

Engineering Success
Contents What’s technical writing…
Objectives
Documents
Before Start
Styles
Mechanics Technical Communication
Mathematics
Reports
Abstracts
 Technical communication is the process of conveying
Tips
Summary
information about technology to an intended audience.
References Technical communication jobs include the following: technical
writer, technical editor, information architect, usability expert,
user interface designer, technical artist and technical trainer.
 A technical writer is a person who creates documentation for a
technology. They are responsible for writing text that is
accurate, readable, accessible and helpful to its intended
audience.
 The technology can be of any kind, including the sciences, high
technology including computers and software, consumer
electronics and so on.

Engineering Success
Contents Two classes of technical documents…
Objectives
Documents
Before Start
Styles
Mechanics Requirements of Software Documents
Mathematics
Reports
Abstracts
 Provide coherent communication between the members of the
Tips
Summary
development team(s)
References  Facilitate the needs of software maintenance
 Give management the information needed to plan and budget the
development process
 User documents –
• Provide the end user with information on how to use the system
• Provide administrators with information on how to administer the
system
Two Classes of Documentation
 Process Documentation
• Records the process of development and maintenance
 Product Documentation
• Describes the product being developed

Engineering Success
Contents Document your processes…
Objectives
Documents
Before Start
Styles
Mechanics Process Documentation
Mathematics
Reports
Abstracts
 Plans, estimates and schedules – used by management to predict
Tips
Summary
and drive the software process
References  Reports – show how resources are used and the progression of
the development process
 Standards – layout how the process should be implemented
 Working papers – ideas and thoughts of the development team
 These often describe implementation strategies
 These often record the rationale for design decisions
 Resume, memos and emails – day-to-day communication…
 Process documents change as the project progresses
 Process documents are somewhat temporary documents
• Although there is much that can be kept for historical purposes
• Historical information can be of value for planning future projects –
1. Estimating, 2. record of how the process evolved for this project
and 3. record of how the ideas evolved

Engineering Success
Contents Document your product…
Objectives
Documents
Before Start
Styles
Mechanics Product Documentation
Mathematics
Reports
 Consists of –
•
Abstracts
Tips User Documentation – describes how to use the product
Summary
References • System Documentation – facilitates software maintenance and
provides an understanding of how the system works
 Permanent documentation that must evolve with the product as
maintenance is performed and enhancements are made
 Should be structured to meet the needs of all users with varying
levels of expertise
 Target audience –
• System Evaluators or management
• Novice Users
• Experienced Users
• System Administrators

Engineering Success
Contents Whom you’re writing for…
Objectives
Documents
Before Start
Styles
Mechanics Product Documentation – Different Types for Different Audience
Mathematics
Reports
Abstracts
Tips
Summary
References
System System Novice users Experienced System

evaluators administrator users administrators
Functional Installation Introduction Reference System
description document manual manual administrators
guide
Description of How to install Getting started Details of all How to
services the system with the system operate and
provided system facilities maintain the
system

Engineering Success
Contents The system engineers need your writing, too…
Objectives
Documents
Before Start
Styles
Mechanics Product Documentation – System Documentation
Mathematics
Reports
Abstracts
 Requirements and associated rationale
Tips
Summary
 Description of system architecture
References  Description of architecture of each program in the system
 Description of the functionality and interfaces of each system
component
 Source code listings
• Explain complex sections of code
• Provide rationale for coding methods used
 Validation documents – describes how each program is validated
against the requirements
 System maintenance guide
• Describes known problems with the system
• Describes hardware and software dependencies
• Describes how evolution of the system was accounted for

Engineering Success
Contents
Objectives You need to keep up the quality…
Documents
Before Start
Styles
Mechanics Maintain Quality Documentation
Mathematics
Reports
 Document quality is important to the life of the system
•
Abstracts
Tips It should be clear how to use a system
Summary
References • It should be easy to understand the system
• The documentation should be up to date
 When system is maintained, it is common to forget about
updating the product documentation
• It is unlikely that the system will be always maintained by the same
developers that created it
• 70% of development costs is spent on maintenance. So it is wise to
make maintenance as easy as possible

Engineering Success
Contents At least, your documents must have these…
Objectives
Documents
Before Start
Styles
Mechanics Minimal Structuring Guidelines
Mathematics
Reports
Abstracts
 Cover page with identification data: title, project name,
Tips
Summary
development team, date of project, intended readers of the
References document, confidentiality, etc.
 Documents of more than a few pages should be broken up into
chapters with sections and subsections. A table of contents
should be added as well
 Documents with detailed reference information should contain
an index
 Glossary may be needed if intended for readers of varying
backgrounds

Engineering Success
Contents
Objectives Most of these are required…
Documents
Before Start
Styles Components of Software User Document
Mechanics
Mathematics Component Required?
Reports
Abstracts Identification data (package label/title page) Yes
Tips
Summary Table of contents Yes, in documents of more than eight pages
References after the identification data
List of illustrations Optional
Introduction Yes
Information for use of the documentation Yes
Concept of operations Yes
Procedures Yes (instructional mode)
Information on software commands Yes (reference mode)
Error messages and problem resolution Yes
Glossary Yes, if documentation contains unfamiliar
terms
Related information sources Optional
Navigational features Yes
Index Yes, in documents of more than 40 pages
Search capability Yes, in electronic documents

Engineering Success
Contents
Objectives Enclave should have standards for you…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Types of Document Standards
Abstracts
Tips For consistency and quality assurance, Enclave should establish the
Summary
References following standards –
 Process standards – define the process for producing high quality
documents
 Product standards – define what the documents should include,
what they should look like, and how they should be maintained
 Interchange standards – specifies what editing system should be
used to maintain documents, and provides standard formatting
rules

Engineering Success
Contents
Objectives Online documents are different…
Documents
Before Start
Styles
Mechanics Online Documentation
Mathematics
Reports
Abstracts
 Do not turn a word-processing document into HTML and call it
Tips
Summary
the online document…
References  Make navigation as easy as possible
• Every page should have a link to the beginning of the document
• Make it easy to get the table of contents
 Provide a printable version of the document
• The HTML pages should not be printed
• There should be a formatted printable version

Engineering Success
Contents
Objectives Always prepare before writing…
Documents
Before Start
Styles
Mechanics Before You Start Writing –
Mathematics
Reports
Abstracts
 Decide what the objective of the report is – Critical; you
Tips
Summary
should have a single clear specific objective. you almost
References certainly produce something that is unsatisfactory
 Write down the objective – One sentence. E.g. the objective of
this document is “to help students write well structured, easy-
to-understand technical reports” to be stated at the beginning
 Always have in mind a specific reader
 Decide what information you need to include
 Have access to a good dictionary
 Identify someone who can provide feedback

Engineering Success
Contents
Objectives Plain English is a good style…
Documents
Before Start
Styles
Mechanics Using Plain English – Styles
Mathematics
Reports
Abstracts
1. Sentence and paragraph length
Tips
Summary
2. Bullet points and enumerated lists
References 3. Using the simplest words and expressions possible
4. Avoiding unnecessary words and repetition
5. Using verbs instead of nouns
6. Using active rather than passive style
7. Using personal rather than impersonal style
8. Explain new ideas clearly
9. Use consistent naming of the same „things‟
10. Painless political correctness

Engineering Success
Contents
Objectives Keep them simple and short…
Documents
Before Start
Styles
Mechanics Sentence and Paragraph Length
Mathematics
Reports
Abstracts
In many cases shorter sentences can be achieved by sticking to the
Tips
Summary
following principles –
References
 A sentence should contain a single unit of information
 Check your sentences for faulty construction.
 Use parentheses sparingly
 A paragraph should have just one idea
 One paragraph should be about 1/3 page or 100 words

Engineering Success
Contents
Objectives Make them easy to recognize…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Bullet Points and Enumerated Lists
Abstracts
Tips In many cases shorter sentences can be achieved by sticking to the
Summary
References following principles –
 If there is no specific ordering of the items in the list then you
should use bullet points instead
 If what you are describing is a list then you should always
display it as a list (when order, total or reference is important)

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Bullet Points and Enumerated Lists (continued)
Abstracts
Tips Example:
Summary
References Getting to university on time for a 9:00 AM lecture involves
following a number of steps. First of all you have to set your
alarm – you will need to do this before you go to bed the
previous night. When the alarm goes off you will need to get out
of bed. You should next take a shower and then get yourself
dressed. After getting dressed you should have some breakfast.
After breakfast you have to walk to the tube station, and then buy
a ticket when you get there.

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Bullet Points and Enumerated Lists (continued)
Abstracts
Tips The following is much simpler and clearer –
Summary
References To get to university on time for a 9:00 AM lecture:
1. Set alarm before going to bed the previous night
2. Get out of bed when the alarm goes off
3. Take a shower
4. Get dressed
5. Have some breakfast
6. Walk to the tube station
7. Buy ticket
8. Catch next train to Stepney Green

Engineering Success
Contents
Objectives The simpler it is, the better it is…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Use Simplest Words and Expressions
Abstracts
Tips The golden rules on words and expressions to avoid are –
Summary
References  Replace difficult words and phrases with simpler alternatives
 Avoid stock phrases
 Avoid legal words and pomposity
 Avoid jargon

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Use Simplest Words and Expressions (continued)
Mathematics
Reports
Replace difficult words and phrases with simpler alternatives
Abstracts Words and expressions to avoid
Tips
Summary
References Word/expression Simple Word/expression Simple
to avoid alternative to avoid alternative
utilize use endeavor try
facilitate help terminate end, stop
at this time now transmit send
in respect of about demonstrate show
commence start initiate begin
terminate end, stop assist, assistance help
ascertain find out necessitate need
in the event of if in excess of more than
in consequence so dwelling house
enquire ask

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Avoid stock phrases
Abstracts
Tips
Summary
References BAD GOOD
There is a reasonable expectation that ... Probably …
Owing to the situation that … Because, since …
Should a situation arise where … If …
Taking into consideration such factors as … Considering …
Prior to the occasion when … Before …
At this precise moment in time … Now …
Do not hesitate to … Please …

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Abstracts
Tips Avoid legal words and pomposity
Summary
References
forthwith hereof of the (4th) inst. thereof
henceforth hereto thereat whereat
here-at herewith therein whereon

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics
Mathematics Use Simplest Words and Expressions (continued)
Reports
Abstracts
Tips
Avoid jargon – BGCOLOR
Summary  If you are certain that every reader of your report understands
References
the specialist field then it can be acceptable to use jargon
 In all other cases jargon should be avoided
 If you cannot avoid it by using alternative expressions then you
should define the term the first time you use it and/or provide a
glossary where it is defined

Engineering Success
Contents
Documents
Before Start
Styles
Mechanics Avoid Unnecessary Words and Repetitions
Mathematics
Reports
Abstracts
 Many sentences contain unnecessary words that repeat an idea
Tips
Summary
already expressed in another word. This wastes space and blunts
References the message
 You should use such abstract words sparingly, if at all
BAD – The product is not of a satisfactory nature.
GOOD – The product is unsatisfactory.
 Unnecessarily complex sentences and genuine redundancy
WITH REDUNDANCY –
The printer is located adjacent to the computer.
WITHOUT REDUNDANCY –
The printer is adjacent to the computer.

Engineering Success
Contents
Objectives Don’t write the same thing twice…
Documents
Before Start
Styles
Mechanics
Mathematics
Avoid Unnecessary Words and Repetitions (continued)
Reports
Abstracts  Another common cause of redundant words is when people use
Tips
Summary
so-called modifying words
References  One of the simplest ways to shorten and simplify your reports is
to remove repetition
BAD GOOD
absolute nonsense nonsense
absolutely critical critical

Engineering Success
Contents
Objectives Verbs are usually shorter than nouns…
Documents
Before Start
Styles
Mechanics
Mathematics Use Verbs Instead of Nouns
Reports
Abstracts  Turning verbs into abstract nouns always results in longer
Tips
Summary sentences than necessary, so you should avoid doing it
References
BAD Half the team were involved in the development of

system Y.
GOOD Half the team were involved in developing system Y.
BAD He used to help in the specification of new software.
GOOD He used to help specify new software.
BAD Clicking the icon causes the execution of the program.
GOOD The program executes when the icon is clicked.

Engineering Success
Contents
Objectives Active forms are usually stronger and shorter…
Documents
Before Start
Styles
Mechanics
Use Active Rather Than Passive Style
Mathematics
Reports
 Using the passive style is the most common reason for poorly
Abstracts structured sentences and it always leads to longer sentences than
Tips
Summary are necessary. Unless you have a very good reason for the
References
change in emphasis
 Use passive style when (Subject + Verb + Object)
• The object is more important than the subject
• You want to hide the subject
 Similarly, for a verb
• Use a noun form of a verb and make it the subject
• Drop the subject. Use command form
BAD The software was tested by Joe.

GOOD Joe tested the software.
BAD The report was written by Bloggs, and was found to be
excellent.
GOOD Bloggs wrote the report, and it was excellent.

Engineering Success
Contents
Objectives You should be friendly in your writing…
Documents
Before Start
Styles
Mechanics Use Personal Rather Than Impersonal Style
Mathematics
Reports
Abstracts
 Whether to use personal or impersonal style is a subject that still
Tips
Summary
causes fierce debate
References  Some writers feel that a report is not truly scientific if it is
written in the personal style
 The most important justification for using first person style is
that it is more natural and results in simpler sentences
BAD The current research work of the author of this report is

also described in the previous report of the authors the
rationale for the proposed method was discussed in
detail.
GOOD I also describe my current research work in our previous
report we discussed in detail the rationale for the
proposed method.

Engineering Success
Contents
Objectives How you can explain things clearly…
Documents
Before Start
Styles
Mechanics Explain New Ideas Clearly
Mathematics
Reports
Abstracts
 Use examples
Tips
Summary
 Use analogies
References  Use a diagram

Engineering Success
Contents
Objectives A word should have one meaning throughout…
Documents
Before Start
Styles
Mechanics
Mathematics Use Consistent Naming
Reports
Abstracts
Tips
 You should always use the same word to refer to the same thing.
Summary Anything else causes confusion and annoyance to readers.
References
 Example –
In the first three weeks of the project we wrote a project plan for
the system. We were ambitious in our requirements because we
wanted the group project to be a success and we wanted the
software to be of high quality. In fact we were determined that
our software would win the prize. By the end of term we
realized there were major problems with the project. The first
increment of the project we delivered was inconsistent with the
requirements specification and it was clear the final code would
not be the best system as there were clearly better groups than
ours.

Engineering Success
Contents
Objectives A word should have one meaning throughout…
Documents
Before Start
Styles
Mechanics Use Consistent Naming (continued)
Mathematics
Reports
Abstracts
We find that these things are referred to at different parts of the
Tips
Summary
paragraph as –
References  The project: project; group project; group
 The plan: project plan; requirements; requirements specification
 The system: system; software; project; code; final code
Not only is there inconsistent naming of the same “things” but we

also find genuine ambiguity because the same words are used to
refer to different “things”

Engineering Success
Contents
Objectives Plural nouns are often better…
Documents
Before Start
Styles
Mechanics Avoid Painless Political Correctness
Mathematics
Reports
Abstracts
 Use plural pronouns instead of singular
Tips
Summary
 Rewrite the sentence in the plural
References  Use “you” or “your”
 Rewrite the sentence to avoid any reference to awkward
pronouns

Engineering Success
Contents
Objectives What we have covered so far…
Documents
Before Start
Styles
Mechanics Summary
Mathematics
Reports
Abstracts
 Keep sentences and paragraphs short
Tips
Summary
 Never use a complicated word or phrase when there is a simpler
References alternative
 Remove and unnecessary words and repetition.
 Use active rather than passive style
 Use active verbs rather than abstract nouns
 Use personal rather than impersonal style
 Explain new ideas clearly by using examples, analogies, and
diagrams

Engineering Success
Contents
Objectives What we have covered so far…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Summary (continued)
Abstracts
Tips  If what you are describing is a list then use an enumerated list or
Summary
References bullet points
 Avoid stock phrases, legal words and pomposity.
 For each abstract “thing” referred to in your report, use a
consistent name to refer to the “thing”
 Use of “he” or “she” to refer to non-specific people is regarded
as politically incorrect and is easy to avoid
 Never use the words utilize or facilitate since these are
respectively the most useless and pompous words in the English
language

Engineering Success
Contents
Objectives Just follow the rules…
Documents
Before Start
Styles
Mechanics Using Plain English – The Mechanics
Mathematics
Reports
Abstracts
 Avoiding common vocabulary and spelling errors
Tips
Summary
 Abbreviations
References  Punctuation

Engineering Success
Contents
Objectives Just use your spell checker…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports
Avoid Common Vocabulary and Spelling Errors
Abstracts
Tips  There is no simple guideline to follow to make sure you always
Summary
References use and spell words correctly.
 There are a number of examples of words that are frequently
misused in place of a similar sounding word with a different
meaning. See table below.
 Use appropriate spellings – e.g.: For U.K. English
• Verbs should end in “-ise” rather than “-ize” as in “generalise” rather
than “generalize” and “formalise” rather than “formalize”
• Words like “colour” and “flavour” should not be written as “color”
and “flavor”

Engineering Success
Contents Be careful with these words…
Objectives
Documents
Before Start
Styles Avoid Common Vocabulary and Spelling Errors (continued)
Mechanics
Mathematics
Reports affect: verb meaning to influence effect: noun meaning result or verb meaning to
Abstracts
Tips bring about
Summary adverse: adjective meaning unfavorable averse: adjective meaning to opposed to or
References
disinclined
principle: noun meaning a standard or rule of principal: adjective or noun meaning most
conduct important
stationery: noun meaning writing materials stationary: adjective meaning not moving
illicit: adjective meaning illegal elicit: verb meaning to give rise to
flaunt: verb meaning to show off flout: verb meaning to show contempt
allusion: noun meaning a passing reference as illusion: noun meaning a false impression
in “were you making an allusion my wife
complement: noun meaning something that compliment: noun meaning praise or verb
completes, or verb meaning to make complete meaning to praise
council: noun meaning an assembly counsel: verb meaning to recommend or noun
meaning recommendation
ensure: verb meaning to make certain insure verb meaning to protect against risk
mitigate: verb meaning to moderate militate: verb meaning to influence (for or
against)
practice: noun as in “put my ideas into practice practice: verb
advice: noun meaning recommendation advise: verb

Engineering Success
Contents Just use your spell checker…
Objectives
Documents
Before Start
Styles
Mechanics Abbreviations and Acronyms
Mathematics
Reports
Abstracts
 Always avoid abbreviating words out of laziness
Tips
Summary
 A long title should not be abbreviated if it is used only once in a
References document
 If it is used more than once then it can be abbreviated to its
initials
 Where initials are used, it is useful to provide a glossary
Note –
 For short phrase and used once, use parenthesis, commas,
dashes, etc.
 For long phrase and used once, use foot note
 For multiple phrase, use glossary

Engineering Success
Contents Punctuations do have their meanings…
Objectives
Documents
Before Start
Styles
Mechanics Punctuations
Mathematics
Reports
Abstracts
 Capital letters
Tips
Summary
 Apostrophes
References  Commas
 Exclamation marks

Engineering Success
Contents Specific names must be capitalized…
Objectives
Documents
Before Start
Styles
Mechanics Capital Letters
Mathematics
Reports
Abstracts
 Organizations and places
Tips
Summary
 Acts of Parliament/Act of Congress
References  Label formed from a proper name
 North, South, East and West when they form part of a country
name but not otherwise
 Titles when used with the name but not otherwise
 Certain periods of history
 God. e.g. I pray to Him/His wills.

Engineering Success
Contents Only use it for these two cases…
Objectives
Documents
Before Start
Styles
Mechanics Apostrophes
Mathematics
Reports
Abstracts
 To show that a letter has been missed out – e.g. – can‟t, doesn‟t,
Tips
Summary
haven‟t, won‟t, etc.
References  To show possession – e.g. – Jack‟s books, Sue‟s desk, etc.
 To show plural s is not part of a foreign word – e.g. – Viet-
kieu‟s; Viet-kieus‟

Engineering Success
Contents List them with commas…
Objectives
Documents
Before Start
Styles
Mechanics Commas
Mathematics
Reports
Abstracts
 Where you are writing a list
Tips
Summary
 Where you are using a qualifying word or expression at the
References beginning of a sentence
 Where the sentence would be ambiguous without it
 To show where you have inserted a phrase
Examples –
 A nice, beautiful girl
 A nicely beautiful girl
 Use (n – 2) instead of (n -1) –
• A, B and C A, B, and C
• A and B A, and B

Engineering Success
Contents Only use it for these two cases…
Objectives
Documents
Before Start
Styles
Mechanics Exclamation Marks
Mathematics
Reports
Abstracts
 Where there is an exclamation – For example, What‟s nice
Tips
Summary
house!
References  As the mathematical notation for the factorial function – For
examples, 4! = 1 * 2 * 3 * 4 = 24

Engineering Success
Contents
Objectives Only three rules for writing with math…
Documents
Before Start
Styles
Mechanics Writing With Mathematics
Mathematics
Reports
Abstracts
 Rule 1: All variables should be in italics to distinguish them
Tips
Summary
from normal text:
References
Incorrect:
The value of a increases when a is less than 100.
Correct:
The value of a increases when a is less than 100.

Engineering Success
Contents Only three rules for writing with math…
Objectives
Documents
Before Start
Styles
Mechanics Writing With Mathematics (continued)
Mathematics
Reports
Abstracts
 Rule 2: When including equations in your work, these should be
Tips
Summary
set out on a separate line and preferably labeled. The dangers of
References not doing so are that –
• The equation may end up stretching onto the next line
• Readers may find it difficult to understand where the text is
separated from the equation
• It is generally much harder to follow
Incorrect
The value of x can be computed as x = 1/y + f(z). In this
equation, f(z) represents a particular function of z.
Correct
The value of x can be computed as:
x = 1/y + f(z) Equation (1)
In Equation (1), f(z) represents a particular function of z.

Engineering Success
Contents
Objectives Only three rules for writing with math…
Documents
Before Start
Styles
Mechanics Writing With Mathematics
Mathematics
Reports  Rule 3: Never start a sentence with a mathematical
Abstracts
Tips symbol of any kind, since this can create genuine
Summary
References ambiguity as well as just being hard to read.
For example –
Incorrect:
We have computed the value of x in terms of y and z. z is
in turn expressed as a function of another variable.
Correct:
We have computed the value of x in terms of y and z. The
variable z is in turn expressed as a function of another
variable.

Engineering Success
Contents
Objectives What we have covered up to now…
Documents
Before Start
Styles
Mechanics Summary
Mathematics
Reports
Abstracts
 The only certain way to avoid spelling errors and
Tips
Summary
incorrect vocabulary is to use a dictionary whenever you
References are unsure of anything
 Use U.S. English rather than U.K. English unless you are
targeting an European audience
 Abbreviations should be used only where necessary.
 Apostrophes should only be used to show possession or to
show that a letter has been missed out
 There are simple rules to learn for when to use commas
 Apart from its special use in mathematics you should only
use an exclamation mark in an exclamation
 If your writing includes mathematical symbols and
formulas follow the rules about how these should be
displayed

Engineering Success
Contents
Objectives What are parts of your report…
Documents
Before Start
Styles
Mechanics Basic Structure For Reports
Mathematics
Reports
Abstracts
 What every report should contain
Tips
Summary
 General layout
References  Sections and section numbering
 The role of introductions
 Figures and tables
 Special section about project reports

Engineering Success
Contents
Objectives Don’t forget any of these…
Documents
Before Start
Styles
Mechanics What Every Report Should Contain
Mathematics
Reports
Abstracts
Make sure every report contains the following basic
Tips
Summary
information:
References  Title
 Author name(s), affiliation and contact details
 Date
 Version number
 Intended Audience
 Abstract (if more than five pages), which is essentially an
executive summary
 Page numbers
 Table of contents (if more than ten pages)
 Conclusions (if more than five pages)

Engineering Success
Contents
Objectives Just use default settings…
Documents
Before Start
Styles
Mechanics General Layout
Mathematics
Reports
Abstracts
 Fonts
Tips
Summary
 Spacing
References  Margins
Use default settings/templates from Microsoft Word

Engineering Success
Contents
Objectives Sections should be up to three levels deep…
Documents
Before Start
Styles
Mechanics Sections and Section Numbering
Mathematics
Reports
Abstracts
Any report longer than five pages should be broken up into
Tips
Summary
sections using the following principles:
References  Sections should be numbered.
 Each section should have a proper heading that accurately
reflects the material contained within it.
 Long sections should be broken up into subsections,
which should be numbered n.1, n.2, etc. where n is the
section number.
 Long subsections should be broken up into sub-
subsections which should be numbered n.m.1, n.m.2, etc.
 Never use numbered decomposition smaller than sub-
subsections.

Engineering Success
Contents
Objectives Tell your readers what you are going to tell them
Documents
Before Start and tell them what you told them…
Styles
Mechanics
Mathematics
Reports Crucial Role of Introductions and Summaries
Abstracts
Tips
Summary
 The first section of any report should be an introduction
References and overview of the entire report
 Where a section is broken into subsections the text
immediately before the first subsection should be an
introduction and overview of the entire section
 Where a subsection is broken into sub-subsections the
text immediately before the first sub-subsection should be
an introduction and overview of the entire subsection

Engineering Success
Contents
Objectives Systematically organize your figures and tables…
Documents
Before Start
Styles
Mechanics
Mathematics
Reports Figures and Tables
Abstracts
Tips  Every figure and table in your document should be
Summary
References numbered and labeled
 Every reference to a figure or table should use the number
of the figure or table
 Every figure or table that appears in the document must
be cited at some point in the document

Engineering Success
Contents Structure your report…
Objectives
Documents
Before Start
Styles
Mechanics Structure of a Project Report
Mathematics
Reports
Abstracts
 Abstract (less than one page)
Tips
Summary
 Table of Contents
References  Chapter 1. Introduction
 Chapter 2. Background/motivation
 Chapter 3. Research
 Chapter 4. Requirements
 Chapter 5. Design
 Chapter 6. Implementation
 Chapter 7. Testing
 Chapter 8. Conclusions and recommendations
 References
 Appendices

Engineering Success
Contents Proofread and check your report…
Objectives
Documents
Before Start
Styles
Mechanics Summary and Checklist
Mathematics
Reports
Abstracts
 Check that the structure conforms to all the rules described
Tips
Summary
above
References  Read it through carefully, trying to put yourself in the shoes of
your potential readers
 Run the document through a spelling/grammar checkers
 Make sure you generate an up to date table of contents and
references to figure and table numbers

Engineering Success
Contents Choose your abstract…
Objectives
Documents
Before Start
Styles
Mechanics Abstracts and Executive Summaries
Mathematics
Reports
Abstracts
There are two types of abstracts – descriptive and informative
Tips
Summary
 Descriptive – A descriptive abstract says what you do in the
References report without providing any of the information or results
 Informative – An informative abstract says what the report
contains, including summarizing the main results. An
informative abstract is also called an executive summary
You should always write informative abstracts rather than
descriptive abstracts. Since informative abstracts are generally
longer, this recommendation may come as a surprise to you.

Engineering Success
Contents Useful tips for you…
Objectives
Documents
Before Start
Styles
Mechanics Tips – How To Write Bad Documentation
Mathematics
Reports
Abstracts
 “Spend lots of time on the appearance and presentation of your
Tips
Summary
documentation. Your management is easily distracted by shiny
References things, and will not realize that your binders contain information
that could easily be recreated by anyone.”
 Document the “What‟s” and not the “Why‟s”. “What” can be
uncovered fairly easily, but “Why” is much more complicated.

Engineering Success
Objectives
Documents
Before Start
Styles
Mechanics
Tips (continued)
Mathematics
Reports
 Avoid wordiness. Say out loud what you are trying to write.
Abstracts
Tips
Listen to how the words sound. “I found out that I should take a
Summary look at our past sales figures in order to come up with a plan to
References
help us re-evaluate our sales technique.” could be “I must take a
look at our past sales figures to re-evaluate our sales technique.”
 Focus on your audience‟s expectation. For example, your
financial report should show the total cost first, then the next
breakdown levels with calculated numbers and so on
 Write for your audience. Use simple language. You don't want
the reader to need a dictionary to decipher what you are trying to
say. You should not try to impress your reader with your huge
vocabulary. Chances are you will frustrate your reader instead.
Most people are juggling several tasks at the same time, and are
interested in receiving only necessary information. "His
gregarious nature credentials him as a superlative candidate for
the job." could be "His friendliness makes him a top candidate
for the job.”
Engineering Success
Contents
Objectives Useful tips for you…
Documents
Before Start
Styles
Mechanics Tips (continued)
Mathematics
Reports
Abstracts
 Your reads are not your guessers or calculators. For examples,
Tips
Summary
“meeting at 8:00 for 2 hours” should be “meeting for 2 hours
References from 8 AM to 10 PM.” The 8:00 can either be 12 or 24 hour
format. Your readers must add 2 hours to 8:00 for the end time.
 Stay away from jargon your reader may not understand. If your
work is very technical, but the person you are writing to is not
well versed in that field, stick to words that person will
understand. For example, if you are a Web site designer, this
sentence in a memo to your client, a psychologist, will make no
sense: "What would you like me to use as the BGCOLOR for
your site: #ADD8E6 or #FFFFFF?" Anyone proficient in Web
page design knows that this question can be translated to "What
would you like the background color of your site to be: Light
Blue or White?" However, don't expect your client to be more
familiar with this technical jargon than you would be with her
discussion of a psychological term such as trichotillomania.

Engineering Success
Contents
Objectives Useful tips for you…
Documents
Before Start
Styles
Mathematics
Reports
Abstracts
 A cliché a day keeps the reader away – or at least it does not
Tips
Summary
make the reader remember what you are saying. You want your
References writing to be memorable. Because we hear clichés often, we
become desensitized to them. The words, then, are not uniquely
associated with your writing. Rather than saying “Don't put off
until tomorrow what you can do today.” in a memo to a
subordinate you are trying to motivate. Simply say, “Stop
procrastinating. Get the job done now.”
 Don't be redundant. It is not necessary to say “2 PM in the
afternoon” or “the expectant pregnant woman.” Saying “2 PM”
or “2 in the afternoon” or “the expectant woman” or “the
pregnant woman” all convey what you want to say and are less
wordy.
 Repeat complex ideas, explaining them in two or more different
ways – from different viewpoints if possible

Engineering Success
Objectives
Documents
Before Start
Styles
Mathematics
Reports
Abstracts
 Do not refer to information by reference number alone. Include
Tips the description for the reference
Summary
References BAD: “Refer to section 1.2.”
GOOD: “Refer to section 1.2, which describes the interface
functional design.”
 Highlight critical information. Use bold type for warnings and
critical information or place a symbol next to the text for
emphasis
 Use tables or screenshots. Your readers will then have a more
reliable document
 Be precise and consistent. When you use a specific term to refer
to a function, continue to use it throughout the publication.
Don‟t change the terms for the sake of variety. This will only
confuse the user!
 Be concise. Use the least possible words to explain concepts,
especially when writing steps in processes and procedures

Engineering Success
Objectives
Documents
Before Start
Styles
Mathematics
Reports
Abstracts
 Proofreading is one of the most important things you can do.
Tips Since you probably do most of your writing on a computer, you
Summary
References have access to automated spelling and grammar checkers.
Beware though – some words, used in the wrong context may be
missed by computerized spell checkers. For example the
sentence "To employees attended too (two) meetings two (to)
learn about the GNU software," would pass through the spell
check without any misspellings being detected. Have someone
else proofread your document, if possible. If time allows, put
your composition away, and proofread it later, or even better, the
next day.
 Of course pay attention to grammar. Use Strunk and White's
Elements of Style, available on the Web. A good dictionary
should be nearby, along with a thesaurus. A thesaurus will allow
you to keep your writing fresh by helping you find a variety of
words to use. Many of these resources are available online.

Engineering Success
Objectives
Documents
Before Start
Styles
Mathematics
Reports  Choose a convention for names to avoid confusion
Abstracts
Tips • Write whole last name in upper-case
Summary
References • Initial middle name
• Write first letter of first name in upper-case
• Use hyphen in multiple words for first name
• NGUYEN M. C. Quyen or NGUYEN M. Chi-Quyen
 Choose a convention for time to avoid confusion
• Use AM and PM for time – e.g. – 6:00 AM, 8:30 PM
• Date – e.g. – Thu, 06-Mar-2008
• The year 08 might be confused for the 8th day of the month
• Weekday should be in three letters because We for Wednesday might
be confused with We as in all of us
 Do not leave any fields on a form or an application blank. Use
N/A, TBA, TBD, unknown, as above,…
 Avoid mindless response such as Level: 0 and Years: 10
 Use precise words – I will e-mail you… instead of I will send
you…

Engineering Success
Objectives
Documents
Before Start
Styles
Mathematics
Reports  Writer writes for reader, not guesser or calculator
Abstracts
Tips
Summary
• My work will take five days from Wed, 01-Sep-2010 to Wed, 08-Sep-
References 2010 excluding the holiday and weekend.
• When writing English, use English number format VND 1,000,000.00
instead of Vietnamese number format 1.000.000,00 VND.
• Use USD for US dollar, AUD for Australian dollar, HKD for Hong
Kong dollar, VND for Vietnamese dong and so on instead of the dollar
sign ($).
• Note the writer‟s nationality shouldn‟t be a necessary piece of
information to understand his or her writing.
• When writing English, use English writing rules and formats. When
writing Vietnamese, use Vietnamese writing rules and formats.

Engineering Success
Contents What we have covered, today…
Objectives
Documents
Before Start
Styles
Mechanics Summary and Conclusions
Mathematics
Reports
Abstracts
 Understand basic definitions, characteristics and concepts in
Tips
Summary
technical writing
References  Distinguish technical writing and general writing
 Understand needs of audience of technical writing
 Have a clear objective in mind before you start writing and make
sure that everything you write is geared towards that objective
alone
 Keep things as simple as possible by using language that is
concrete and familiar
 Keep sentences and paragraphs short
 Avoid long, pompous words and phrases when there is a short
simple alternative
 Avoid unnecessary words, clichés and legal words
 Avoid repetition

Engineering Success
Contents What we have covered, today…
Objectives
Documents
Before Start
Styles
Mechanics Summary and Conclusions (continued)
Mathematics
Reports
Abstracts
 Use active rather than passive style
Tips
Summary
 Do not turn verbs into nouns
References  Use personal rather than impersonal style
 Always refer to the same “thing” in exactly the same way
 Make sure all reports conform to the basic structure described
 Use examples and analogies before introducing abstract
concepts
 Use a dictionary, and make sure you learn the words that are
commonly misspelled or misused
 Write informative (rather than descriptive) abstracts
 If your writing includes mathematical symbols and formulas
follow the rules about how these should be displayed

Engineering Success
Contents If you want to learn more…
Objectives
Documents
Before Start
Styles
Mechanics References
Mathematics
Reports
Abstracts
 Jay R, “How to Write proposals and reports that get results”,
Tips
Summary
Pearson Education Ltd 2000, ISBN 0 273 64497 1.
References  Kirkman J, “Good ttyle; writing for science and technology”, E
and FN Spon, London 1992.
 O‟Connor M, “Writing successfully in science”, Chapman and
Hall, London 1991.
 Turk C, and Kirkman J, “Effective Writing: Improving Scientific,
Technical and Business Communication”, E and FN Spon,
London 1989.
 “Improving Your Technical Writing Skills”, Norman Fenton.

Engineering Success
Contents If you want to learn more…
Objectives
Documents
Before Start
Styles
Mechanics References (continued)
Mathematics
Reports
Abstracts
 Ian Sommerville, “Software Documentation” Software
Tips
Summary
Engineering Volume 2: The Supporting Processes Second
References Edition, John Wiley & Sons, Inc., Hoboken, NJ, 2003, pp. 171-
185.
 Software Engineering Standards Committee of the IEEE
Computer Society, “IEEE Standard 1063-2001 Software User
Documentation” Software Engineering Volume 2: The
Supporting Processes Second Edition, John Wiley & Sons, Inc.,
Hoboken, NJ, 2003, pp. 187-196.
 clover_kicker, “HOWTO: write bad documentation that looks
good”, http://www.kuro5hin.org/story/2003/9/29/104212/112
 Deepa L. Melonfire, “Writing A User Manual”,
http://www.devshed.com/c/a/Practices/Writing-A-User-Manual-
part-1/1/, December 2002.

Engineering Success
The End…
Thank you!
Your questions are welcome.

Engineering Success

E Technical Writing Pp3

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

E Technical Writing Pp3

Caricato da

Copyright:

Formati disponibili

Technical Writing Skills

Author: Hung H. Le, CEO

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

System System Novice users Experienced System

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

BAD Half the team were involved in the development of

Danang 31-Jul-2007 Enclave®

BAD The software was tested by Joe.

Danang 31-Jul-2007 Enclave®

BAD The current research work of the author of this report is

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Not only is there inconsistent naming of the same “things” but we

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®

Danang 31-Jul-2007 Enclave®