1

Introduction to

Technical Writing

(Technical Writing CS212)

Lecture 1

Abdisalam Issa-Salwe

Taibah University

College of Computer Science & Engineering

Computer Science Department

2

Outline

1. About Technical Writing

2. Technical vs. academic writing

3. Essential Skills of a Technical Writer

4. Technical Writing Myths

5. Audience Analysis

2

3

About Technical Writing

� Communication is part of the life of every creature on this planet.

� How that communication is carried out however, is varied, and different types of communication are suitable based upon the type of information that needs to be conveyed.

� One specific area of communication involves transmitting, understanding and knowledge of a technical subject to others that need to know the basics and details of the subject in question.

� In written form, this communication type of communication is called technical writing.

4

About Technical Writing (cont…)

� What is Technical Writing?

�Taking complicated subject matter and transforming it into easy-to-understand information for the reader.

3

5

About Technical Writing (cont…)

� Technical writing is the presentation of information that helps the reader solve a particular problem.

� Technical communicators write, design, and/or edit proposals, manuals, web pages, lab reports, newsletters, and many other kinds of professional documents.

� While technical writers need to have good computer skills, they do not necessarily have to write about computers all their lives.

� "Technical" comes from the Greek techne, which simply means "skill".

� Every profession has its own special specialized forms of writing.

6

About Technical Writing (cont…)

� Technical writers represent those who write technical and software manuals, handbooks, technical guides and provide online help; anyone who writes about technology for other people is typically referred to as a technical writer.

� Most professionals require some technical writing skills.

� In the information technology realm, project managers and analysts write a large number of technical documents that must be clear and concise.

4

7

About Technical Writing (cont…)

� When technical writers approach a new piece of technology, they are inwardly observing their own lack of knowledge.

� As they interact with and learn the software, they identify the information needs of the software users.

� They must be able to communicate well with programmers and customers, and extract information from them in a professional and personable manner.

� A technical writer's primary tool is the language.

� Technical writers communicate ideas; they design information, participate in the product development process, and manage complex documentation projects.

8

How is Technical Writing Different?

� The information is organized, presented and

communicated in a specific format.

� The writing is concise, clear and accurate.

� The writing takes into account the audience’s needs,

biases and prior understanding.

� The writing presents information to help readers

solve a problem or gain a better understanding of a

situation.

� The writing conveys technical, complex, or

specialized information in a way that is easy for a

non-technical reader to understand.

5

9

How is Technical Writing Different? (cont…)

� Technical writing is

� objective

� direct

� clearly defined

� precise

10

What Technical Writing is Not

� Subjective

� Metaphorical

� Technical writing avoids figures of speech

such as metaphors and similes, symbolic

language, and abstraction to restrict

readers’ freedom of interpretation.

6

11

How is Technical Writing Different?

� Technical writing achieves precision with:

definitions and descriptions photographs

and drawings numerical data and

mathematical equations

� tables and charts

12

Why should you care about writing?

� You must communicate your work to the world

� If people don’t know about it, they won’t use it

� Increase probability of adoption

� Clear writing requires clear thinking; muddled writing is a sign of muddled thought

� Be kind to your readers good writing can be a joy; bad writing is agony

� These skills transfer to other endeavors

7

13

�Technical writing is a natural partner to academic writing. �It is descriptive, creative, and expository, but the format is different and the standards are higher.�Technical writing requires 100% accuracy.�Technical writing is effective when:

�the writer communicates precisely his/her intended meaning to his/her reader.

�the writing fulfils its goal or intended purpose.

Essential Skills of a Technical Writer

14

Essential Skills of a Technical Writer

� There are five important skills or characteristics which are "musts" for the technical writer:

1. Facility with technology: You must have the potential to grasp intended technology.

2. Ability to write clearly: The essential skill of any technical communicator is to disambiguate.

3. Talent in showing ideas graphically: People understand better when you can communicate your ideas visually. These images go a long way toward making your writing clear.

4. Patience in problem-solving/troubleshooting: Unless you have patience, you’ll never make it

5. Ability to interact with Subject Matter Experts (SME): Interacting with SMEs is one of the most overlooked skills in technical writing.

8

15

Academic Writing Technical Writing

Descriptive Writing Job Description, Incident Report,

Résumé, Process Explanation

Narrative Writing Observation Report, Progress

Report

Analysis Performance Evaluation,

Feasibility Report

Cause and Effect Analytical Report, Product Field

Test Report

Compare-Contrast Product Comparison, Feasibility

Report

Persuasive Writing Proposal, Action Plan

16

Examples of Technical Writing:

• Action Plans

• Advertisement

• Agenda

• Audit Report

• Book Review

• Brochure

• Budget

• Business Letter

• Business Plan

• Catalog

• Contract

• Critique

• Data Book or Display

• Description

• Diagram, Chart, or Graph

• Editorial

• Email

• Feasibility Report

• Field Test Report

• Incident Report

• Informational Form

• Informational Poster

• Informative Summary

• Instructions

• Interview Questions

• Itinerary

9

17

What do Tech Writers create?

� User’s manuals

� System manuals

� Step-by-step procedures

� On-line help

� Training manuals

� Quick-reference guides

� How-to video scripts

18

Identify the audience

� Potential audience includes:

�Experts in your area; people outside your area

�Expert professors; advanced undergrads

� Industry practitioners

�Researchers now; researchers 10 years from now

10

19

References

- The Essence of Computing Projects: A Student’s Guide,

by Christian W. Dawson, Prentice Hall.

- Mohammad Alsuraihi, Technical Writing, CS212 Course

notes, Taibah University, Madinah, KSA

- Abdisalam Issa-Salwe, Taibah University, Madinah,

Saudi Arabia.

- Technical writing overview,

http://en.wikiversity.org/wiki/Technical_writing_overview