TECHNICAL WRITING

TECHNICAL WRITING

PROF. DR. MOHAMED REFAAT DIAB AHMED

1

LECTURE ONE PART 1 INTRODUCTON

 A technical subject is one that falls within the specialized areas of engineering or science or interpretation of subject matter.

The main purposes of Technical writing are:

1· to inform:

2· to instruct:

3 · to propose:

4· to recommend:

5· to persuade:

2

Technical writing

Classified into three categories:

1. Technology Education:

Writing to show non-technical readers how to use or do something.

2. Traditional Technical Writing:

Writing for technical readers.

3. Technology Marketing:

Writing marketing materials and corporate communications for and within technical fields like computers, aerospace, etc.

3

The General Characteristics Of Technical Writing : 1. Its formal aspect

2. Its scientific point of view

3. The specific techniques of technical writing BASIC ASPECTS OF TECHNICAL WRITING

Technical writing can be divided into two parts:

o The end product.

o The Technical Writing skills that enter into the preparation of the end product.

4

A. The End Product

Various types of written reports Oral reports:

Formal discussion of technical problems.

Formal speech.

Company’s technical documentation Articles for technical journals

Books and Handbooks Abstracts

Biographies

5

Broachers

Comparison and Contrast Essays Definition and Descriptive Essays Business letters

Instruction manuals Memoranda

Newsletters

6

The End Product

 Plans

 Proposals

 Persuasive and Process Essays

 Presentations

 Graphic aids a. Graphs b. Drawings

c. Non-textual supplements

 Press Release

 Proposals

 Reviews

 Resumes

 Reaction Papers

 Research Papers

• Specifications

7

Examples Of Type Of Reports:

- Preliminary - Inspection - Partial - Information - Final - Work

- Completion - Shop

- Progress - Investigation - Experimental - Research

- Evaluation - Service - Test - Operation

- Periodic - Construction - Design - Examination - Recommendation

8

Some Of Technical Writing: Important Types

1. Research Report

2. Simple Technical Information Report 3. Technical Specifications:

4. Technical Recommendation Reports 5. Proposals

9

6

- Addendum: - Application Notes/Briefs:

- Architectural Overviews/specs: - Benchmark documents:

- Datasheets: - Data book:

- Design Guide: - Design Specification:

- Electronic Design Kit - Engineering Bulletin:

- Errata - Installation Guide:

- Hardware Manual: - Packaging Guide

- Product Brief: - Programmers Reference Manual: - Product specifications:

Electrical specifications,

Thermal specifications,

Mechanical specifications.

-Programmers Reference Manual - Software Manual: - Requirement’s specifications:

- Specification Updates:

- Technical Manuals and Instructions:

10

The Technical Writing Skills

Technical writing is a specialized field that requires personal discipline, skills in writing clearly and concisely, understanding of technical products and processes, organization skill, and knowledge of numerous software tools.

11

Fundamental Skills Required in Technical Writing are:

1. Special techniques of technical writing:

The most important are: description of mechanism, definition, classification, etc.

2. Style:

A quality determined by the relative smoothness or awkwardness with which sentences are put together.

The point of view should be scientific: objective, impartial, and unemotional.

3. Introduction, transition, and conclusions:

Learn to tell the reader what you are going to tell him, then to tell him, and then tell him what you have told him.

12

4.Outline(or organization):

It is the theory of organizing the writing.

5. Layout, or format of reports: it has to do with such matters as:

a. Font

b.Margins

c. Labeling for figures and graphics d.Line and paragraph spacing

e. Number of words per document or per section f. Section headings and subheadings

Constant attention should be given to spelling, grammar, and punctuation.

13

The Writer Should Be Sure He Knows The Basic Rules For Using

a. Commas b.Colons

c. Semicolons d.Hyphens

e. Acronyms Numbers (writing the word vs. using the numeral) f. Equations (use symbols)

g.Units of Measure (70 ns, 100 dB)—use abbreviations and symbols

14

APPROACH TO WRITING

The point of attack in report writing is the analysis of the problem.

In analyzing a writing problem, the following questions should be asked:

1.What is the purpose of the report?

2.Who will read it?

3.How will it be used?

4.What is wanted?

5.When is it wanted?

6.What decisions will be based on the report?

7. What does the reader need to be told in order to understand the material?

15

BASIC PRINCIPLES OF GOOD TECHNICAL WRITING

There are many principles involved in good technical writing, among these: 1. Understand the type of technical report you are writing:

 Technical reports come in all shapes and sizes.

 They all share the same goal of communicating information clearly.

 Deciding what type of document you need to write.

 Always have in mind a specific reader, or imaginary, when you are writing a report.

 Always assume that he is intelligent, but uninformed 2. Before starting writing

Always decide what the exact purpose of your report is.

Make sure that

every paragraph,

every sentence,

every word

makes a clear contribution to that purpose

16

3. Use language that is simple, concrete and familiar. Get to the point. Provide accurate information.

4. At the beginning and end of every section of the report check your writing according to this principle:

“First you tell the reader what you’re going to tell him, then you tell him, then you tell him what you’ve told him.”

 Make your report attractive to look at.

 Present document material logically.

 Make ideas accessible.

 Use lists for some information.

 Satisfy document specifications

17

STYLE IN TECHNICAL WRITING

It may be defined as:

 The dress of thoughts is.

 The qualities, clarity, order, logic, ease, unity, coherence, rhythm, force, simplicity, naturalness, grace, wit (intelligence), and movement.

 Proper words in proper places.

 The way you write.

This means the way you put words together in sentences, the way you arrange sentences into paragraphs, and

the way you group paragraphs to make a whole composition.

18

Technical style is way you write when dealing with technical subject matter.

It is distinguished by:

- A calm, restrained tone,

- The use of specialized terminology,

- An accepted convention of the use of abbreviations, numbers and symbols.

19

THE MAIN FEATURES OF TECHNICAL WRITING ARE

1. Keeping information specific rather than general:

- General: heavy precipitation during the period Specific: four centimeters of rain in 48 hours

- General: excessive heat

Specific: 300 degree centigrade - General: select the appropriate key Specific: click Alt-B

2. Providing accurate information:

 Technical writer must be truthful and accurate in transmitting any technical information (facts, theories, experimental results, etc.).

 Technical writing is rarely about opinion.

3. Using appropriate writing style 4. Avoiding personal pronoun

20

5. Avoiding Conversational Tone: technical documents should employ a formal writing style. Conversational language and phrasing should be avoided.

- Conversational: This lab gave us a good feel for state machines.

- Formal: This exercise provided a good background on state machine design.

6. UNITY:

Each paragraph is a block or unit of thought.

It should present only one topic or one part of a topic.

All the facts, examples, and reasons in a unified paragraph should explain this thought

7. CONSISTENCY:

Consistency reflects a good impression on the reader as it shows that the writer knows what he is writing. Inconsistencies will confuse the reader and convince him that the writer is unprofessional and careless.

The rules of numbers, units, capitalization, punctuation, abbreviations, and grammar must be uniformly followed through-out the technical document.

21

8. Organizing Information Logically and Linearly: in general, technical writing is organized in a direct, linear format. All technical documents have a clear:

a. Introduction: where providing a global picture of motivation and context/background for the topic/ material/ information being presented in his document.

b. Body: where the information is expounded upon and where technical details are given.

c. Conclusion: where the main points are reemphasized and where the global picture is once again discussed.

22

9. EXPRESSING INFORMATION CLEARLY:

 Avoid any expression, statement, situation, etc. that can be variously interpreted.

 Passive sentences and long constructions should be avoided.

Sentences must have a single meaning.

 They shouldn’t be variously interpreted.

 Technical writing should be direct, not suspenseful (being uncertain or doubtful).

 Technical writing is not the place for poetic language.

 Comments, hints, suggestions should be direct and straightforward in expressing and meaning

23

10.COHERENCE:

Coherence is the straight line of development within a paragraph or a text.

A paragraph is coherent when its ideas are clearly related to each other in an orderly sequence. Each sentence in a coherent paragraph naturally leads to the next sentence in explaining the controlling idea.

To gain coherence, a writer should decide before writing how each paragraph will be built. There many possibilities:

a.Development from least important to most important example.

b.Development from most important to least important example.

c.Development by time (chronologically). Sentences follow each other in time.

They are arranged in order in which they actually happen.

d.Development by space (spatially). One way to organize spatially is to begin with an object that is farthest away from a viewer and in each sentence move gradually closer to the point where the viewer standing.

e.Development from specific facts to generalization.

f.Development from generalization to specific facts.

24

11. MAKING IDEAS/INFORMATION ACCESSIBLE

Technical document is characterized by its page layout and organizational structure.

Technical writing is known for its use of headings and subheadings and for the way information is made easily accessible by presenting material in groups.

 Paragraphs are usually much shorter in technical writing than in other types of writing.

 Readers want to be able to quickly access information.

The writer should try to make information visual by creating figures and graphics. Figures and tables help the reader to access important data.

25

13.CONCISION:

Concise technical writing is easier and less time consuming to read than wordy technical writing.

Concision is achieved when expressing much in brief form; compact.

Technical writing is in some degree designed for a particular reader or group of readers.

 The writer should never write with the assumption that his reader is informed about his particular subject.

12. PERSUASION:

The main goal of technical writing is to transmit technical information, while its secondary goal is to persuade.

Nevertheless, a technical writer has to remember that people in technical fields tend to make their decisions based more on logic and rational thoughts than on emotions and cuteness.

26

14. ELEMENTS REQUIRING ADAPTATION:

All elements in technical writing are influenced in some way by the intended reader.

Three particular elements of style should be given first attention in adapting 1. Vocabulary: the writer shouldn’t use words his reader won’t know.

When he does want to use a word that may not be familiar to him, he should define it.

2. Sentence: it should be relatively short, and should be simple in construction.

3. Organization: the principal parts of a report should be adapted to a reader.

27