e technical writing pp3

8/8/2019 E Technical Writing Pp3

http://slidepdf.com/reader/full/e-technical-writing-pp3 1/71

Danang 31-Jul-2007 Enclave ®

Engineering Success

Author: Hung H. Le, CEO

Date: 09-Aug-2007

Duration: 3 Hours

Technical Writing Skills




Engineering Success

It’s all about writings…

Contents

Session Objectives

Definitions – Technical Communication, Technical Writing, Technical Writerand Technical Documents

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 intosections 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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

What you need to improve your writing…

Session Objectives

To understand basic definitions, characteristics and concepts intechnical writing

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

What’s technical writing…

Technical Communication

Technical communication is the process of conveyinginformation about technology to an intended audience.

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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Two classes of technical documents…

Requirements of Software Documents

Provide coherent communication between the members of thedevelopment team(s)

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Document your processes…

Process Documentation

Plans, estimates and schedules – used by management to predictand drive the software process

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References


http://slidepdf.com/reader/full/e-technical-writing-pp3 7/71Danang 31-Jul-2007 Enclave ®

Engineering Success

Document your product…

Product Documentation

Consists of – • User Documentation – describes how to use the product

• 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 varyinglevels of expertise

Target audience – • System Evaluators or management

• Novice Users

• Experienced Users

• System Administrators

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

Whom you’re writing for…

Product Documentation – Different Types for Different Audience

System

evaluators

System

administrator

Novice users Experienced

users

System

administrators

Functional

description

Installation

document

Introduction

manual

Reference

manual

System

administrators

guide

Description of

services

provided

How to install

the system

Getting started

with the

system

Details of all

system

facilities

How to

operate and

maintain thesystem

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

The system engineers need your writing, too…

Product Documentation – System Documentation

Requirements and associated rationale Description of system architecture

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

You need to keep up the quality…

Maintain Quality Documentation

Document quality is important to the life of the system• It should be clear how to use a system

• 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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

At least, your documents must have these…

Minimal Structuring Guidelines

Cover page with identification data: title, project name,development team, date of project, intended readers of the

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

Most of these are required…

Components of Software User Document

Component Required?

Identification data (package label/title page) Yes

Table of contents Yes, in documents of more than eight pages

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References



Engineering Success

Enclave should have standards for you…

Types of Document Standards

For consistency and quality assurance, Enclave should establish the

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Online documents are different…

Online Documentation

Do not turn a word-processing document into HTML and call itthe online document…

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Always prepare before writing…

Before You Start Writing –

Decide what the objective of the report is – Critical; youshould have a single clear specific objective. you almost

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Plain English is a good style…

Using Plain English – Styles

1. Sentence and paragraph length2. Bullet points and enumerated lists

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 style8. Explain new ideas clearly

9. Use consistent naming of the same „things‟

10. Painless political correctness

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Keep them simple and short…

Sentence and Paragraph Length

In many cases shorter sentences can be achieved by sticking to thefollowing principles –

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Make them easy to recognize…

Bullet Points and Enumerated Lists

In many cases shorter sentences can be achieved by sticking to thefollowing 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)

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success


Bullet Points and Enumerated Lists (continued)

Example:

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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success


Bullet Points and Enumerated Lists (continued)

The following is much simpler and clearer –

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 dressed5. Have some breakfast

6. Walk to the tube station

7. Buy ticket

8. Catch next train to Stepney Green

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

The simpler it is, the better it is…

Use Simplest Words and Expressions

The golden rules on words and expressions to avoid are –

Replace difficult words and phrases with simpler alternatives

Avoid stock phrases

Avoid legal words and pomposity

Avoid jargon

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success


Use Simplest Words and Expressions (continued)

Replace difficult words and phrases with simpler alternatives

Words and expressions to avoid

Word/expression

to avoid

Simple

alternative

Word/expression

to avoid

Simple

alternative

utilize use endeavor try

facilitate help terminate end, stopat 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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success



Avoid stock phrases

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 …

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success



Avoid legal words and pomposity

forthwith hereof of the (4th) inst. thereof

henceforth hereto thereat whereat

here-at herewith therein whereon

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success



Avoid jargon – BGCOLOR If you are certain that every reader of your report understands

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 aglossary where it is defined

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success


Avoid Unnecessary Words and Repetitions

Many sentences contain unnecessary words that repeat an idea

already expressed in another word. This wastes space and blunts

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 redundancyWITH REDUNDANCY –

The printer is located adjacent to the computer.

WITHOUT REDUNDANCY –

The printer is adjacent to the computer.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Don’t write the same thing twice…

Avoid Unnecessary Words and Repetitions (continued)

Another common cause of redundant words is when people useso-called modifying words

One of the simplest ways to shorten and simplify your reports is

to remove repetition

BAD GOODabsolute nonsense nonsense

absolutely critical critical

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Verbs are usually shorter than nouns…

Use Verbs Instead of Nouns

Turning verbs into abstract nouns always results in longersentences than necessary, so you should avoid doing it

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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Active forms are usually stronger and shorter…

Use Active Rather Than Passive Style

Using the passive style is the most common reason for poorly

structured sentences and it always leads to longer sentences thanare necessary. Unless you have a very good reason for the

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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

You should be friendly in your writing…

Use Personal Rather Than Impersonal Style

Whether to use personal or impersonal style is a subject that still

causes fierce debate

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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

How you can explain things clearly…

Explain New Ideas Clearly

Use examples

Use analogies

Use a diagram

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

A word should have one meaning throughout…

Use Consistent Naming

You should always use the same word to refer to the same thing.Anything else causes confusion and annoyance to readers.

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 thesoftware 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.

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

A word should have one meaning throughout…

Use Consistent Naming (continued)

We find that these things are referred to at different parts of the

paragraph as –

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 wealso find genuine ambiguity because the same words are used to

refer to different “things”

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Plural nouns are often better…

Avoid Painless Political Correctness

Use plural pronouns instead of singular

Rewrite the sentence in the plural

Use “you” or “your”

Rewrite the sentence to avoid any reference to awkward

pronouns

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Wh t h d f




Engineering Success

What we have covered so far…

Summary

Keep sentences and paragraphs short

Never use a complicated word or phrase when there is a simpler

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

What we have covered so far…

Summary (continued)

If what you are describing is a list then use an enumerated list orbullet 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 regardedas 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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Just follow the rules…

Using Plain English – The Mechanics

Avoiding common vocabulary and spelling errors

Abbreviations

Punctuation

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References




Engineering Success

Just use your spell checker…

Avoid Common Vocabulary and Spelling Errors

There is no simple guideline to follow to make sure you alwaysuse 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”

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Be careful with these words




Engineering Success

Be careful with these words…

Avoid Common Vocabulary and Spelling Errors (continued)

affect: verb meaning to influence effect: noun meaning result or verb meaning to

bring about

adverse: adjective meaning unfavorable averse: adjective meaning to opposed to or

disinclined

principle: noun meaning a standard or rule of

conduct

principal: adjective or noun meaning most

important

stationery: noun meaning writing materials stationary: adjective meaning not moving

illicit: adjective meaning illegal elicit: verb meaning to give rise toflaunt: verb meaning to show off flout: verb meaning to show contempt

allusion: noun meaning a passing reference as

in “were you making an allusion my wife

illusion: noun meaning a false impression

complement: noun meaning something that

completes, or verb meaning to make complete

compliment: noun meaning praise or verb

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Just use your spell checker




Engineering Success

Just use your spell checker…

Abbreviations and Acronyms

Always avoid abbreviating words out of laziness

A long title should not be abbreviated if it is used only once in a

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

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Punctuations do have their meanings




Engineering Success

Punctuations do have their meanings…

Punctuations

Capital letters

Apostrophes

Commas

Exclamation marks

Contents

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Specific names must be capitalized…Contents




Engineering Success

Specific names must be capitalized…

Capital Letters

Organizations and places

Acts of Parliament/Act of Congress

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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Only use it for these two cases…Contents



Danang 31-Jul-2007 Enclave ® Engineering Success

Only use it for these two cases…

Apostrophes

To show that a letter has been missed out – e.g. – can‟t, doesn‟t,

haven‟t, won‟t, etc.

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‟

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

List them with commas…Contents




List them with commas…

Commas

Where you are writing a list

Where you are using a qualifying word or expression at the

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

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Only use it for these two cases…Contents




Only use it for these two cases…

Exclamation Marks

Where there is an exclamation – For example, What‟s nice

house!

As the mathematical notation for the factorial function – For

examples, 4! = 1 * 2 * 3 * 4 = 24

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Only three rules for writing with mathContents




Only three rules for writing with math…

Writing With Mathematics

Rule 1: All variables should be in italics to distinguish them

from normal text:

Incorrect:

The value of a increases when a is less than 100.

Correct:

The value of a increases when a is less than 100.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Only three rules for writing with math…Contents




y g

Writing With Mathematics (continued)

Rule 2: When including equations in your work, these should be

set out on a separate line and preferably labeled. The dangers of

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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Only three rules for writing with mathContents




Only three rules for writing with math…

Writing With Mathematics

Rule 3: Never start a sentence with a mathematical

symbol of any kind, since this can create genuineambiguity 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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

What we have covered up to nowContents




What we have covered up to now…

Summary

The only certain way to avoid spelling errors and

incorrect vocabulary is to use a dictionary whenever you

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 toshow 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 andformulas follow the rules about how these should be

displayed

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

What are parts of your reportContents




What are parts of your report…

Basic Structure For Reports

What every report should contain

General layout

Sections and section numbering

The role of introductions

Figures and tables

Special section about project reports

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Don’t forget any of theseContents

Obj i




Don t forget any of these…

What Every Report Should Contain

Make sure every report contains the following basic

information:

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)

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

AbstractsTips

Summary

References

Just use default settingsContents

Obj ti




Just use default settings…

General Layout

Fonts

Spacing

Margins

Use default settings/templates from Microsoft Word

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Sections should be up to three levels deepContents

Obj ti




Sections should be up to three levels deep…

Sections and Section Numbering

Any report longer than five pages should be broken up into

sections using the following principles:

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 thesection 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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Tell your readers what you are going to tell themContents

Objectives




Tell your readers what you are going to tell them

and tell them what you told them…

Crucial Role of Introductions and Summaries

The first section of any report should be an introduction

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 thetext immediately before the first sub-subsection should be

an introduction and overview of the entire subsection

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Systematically organize your figures and tablesContents

Objectives




Systematically organize your figures and tables…

Figures and Tables

Every figure and table in your document should benumbered 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

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Structure your report…Contents

Objectives




Structure of a Project Report

Abstract (less than one page)

Table of Contents 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

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Proofread and check your report…Contents

Objectives




Summary and Checklist

Check that the structure conforms to all the rules described

above 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

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Choose your abstract…Contents

Objectives




Abstracts and Executive Summaries

There are two types of abstracts – descriptive and informative

Descriptive – A descriptive abstract says what you do in thereport 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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Useful tips for you…Contents

Objectives




Tips – How To Write Bad Documentation

“Spend lots of time on the appearance and presentation of your

documentation. Your management is easily distracted by shinythings, 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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

Useful tips for you…

Contents

Objectives




Tips (continued)

Avoid wordiness. Say out loud what you are trying to write.

Listen to how the words sound. “I found out that I should take alook at our past sales figures in order to come up with a plan to

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 areinterested 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.”

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives




p y

Tips (continued)

Your reads are not your guessers or calculators. For examples,

“meeting at 8:00 for 2 hours” should be “meeting for 2 hoursfrom 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 willunderstand. 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 "Whatwould 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.

Objectives

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives




p y

Tips (continued)

A cliché a day keeps the reader away – or at least it does not

make the reader remember what you are saying. You want yourwriting 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, “Stopprocrastinating. 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 lesswordy.

Repeat complex ideas, explaining them in two or more different

ways – from different viewpoints if possible

j

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives




Tips (continued)

Do not refer to information by reference number alone. Include

the description for the referenceBAD: “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 foremphasis

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

j

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives




Tips (continued)

Proofreading is one of the most important things you can do.

Since you probably do most of your writing on a computer, youhave 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 spellcheck 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.

j

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives

http://clk.about.com/?zi=1/XJ&sdn=careerplanning&zu=http://www.bartleby.com/141/index.html

http://clk.about.com/?zi=1/XJ&sdn=careerplanning&zu=http://www.freeality.com/dictionat.htm

http://clk.about.com/?zi=1/XJ&sdn=careerplanning&zu=http://www.freeality.com/dictionat.htm

http://clk.about.com/?zi=1/XJ&sdn=careerplanning&zu=http://www.bartleby.com/141/index.html




Tips (continued)

Choose a convention for names to avoid confusion

• Write whole last name in upper-case• 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. UseN/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…

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References


Objectives




Tips (continued)

Writer writes for reader, not guesser or calculator

• My work will take five days from Wed, 01-Sep-2010 to Wed, 08-Sep-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.

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

What we have covered, today…Contents

Objectives




Summary and Conclusions

Understand basic definitions, characteristics and concepts in

technical writing 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

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

What we have covered, today…Contents

Objectives




Summary and Conclusions (continued)

Use active rather than passive style

Do not turn verbs into nouns 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

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

If you want to learn more…Contents

Objectives




References

Jay R, “How to Write proposals and reports that get results”,

Pearson Education Ltd 2000, ISBN 0 273 64497 1. 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.

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

If you want to learn more…Contents

Objectives




References (continued)

Ian Sommerville, “Software Documentation” Software

Engineering Volume 2: The Supporting Processes SecondEdition, 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: TheSupporting 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.

Documents

Before Start

Styles

Mechanics

Mathematics

Reports

Abstracts

Tips

Summary

References

The End…



Thank you!

Your questions are welcome.