Technical Writing

1 The views expressed are based on personal experience and information collected from the net.

2

What is Technical Writing?

Technical writing is the

process of conveying technical information through writing to a specific audience. In other words, it is a technical communication!

3

Importance

Conveying technical ideas is a significant component of a software professional’s responsibilities

You will often be judged on the basis of what you write, and how you write it

Good technical writing makes life easier all round Bad technical writing can ruin a project or product

4

Qualities of good technical writing

Planning Clarity Brevity Simplicity Word Choice Active Voice

5

Before you begin

Identify your audience and their expectations Know your purpose Know your material Understand the writing task at hand Organize your thoughts and materials Budget adequate time to write, review, revise, and edit.

6

Know your audience

Who they are What do they know Why they will read How they will read

7

Why?

Purpose / What are the goals of a technical document ? Describe Compare Explain Analyze Support Refute

8

What?

Different types of technical documents Requirements Specifications System Architecture Document High level / Low level Design Document Test Plan Test Reports Reference Manual User Guide Release Notes Performance Measurement Document Competitive Analysis Document Status Reports

9

What? (contd.)

Different types of technical documents Bug Reports Release Notes Defect Analysis Validation Performance Reports

10

How do they differ?

Intent Audience Level of technical details Presentation style

e.g; man pages, Windows help files

11

How?

Content Organization Style Gotchas...

12

Content

What do you want to say? Why do you want to say it? What do you need to say? Can you explain it to yourself?

Who is your audience? Architects? Programmers? Naïve Users?

13

Content Vs. Presentation

Focus on the contents - Presentation comes later Worrying about fonts, margins, pagination, etc. too early

takes away time better spent in composition Do a “Presentation Pass” after you have the content and

organization worked out

14

The ABCs of Technical Writing

Accuracy Mean what you say

Brevity …Is the Soul of Wit

Clarity Say what you mean

15

Organization

Abstract / Introduction / Overview / Objective Follow a natural logical order Be gentle to the reader Overall coherence References Summary / Conclusion

16

Organization...

Sketch out an outline and fill it in Don’t lose context Top Down rather than Bottom Up Be prepared to make several passes Keep the whole in mind when you work on the parts

It is easy to lose your message through being sloppy, careless or indifferent to detail

17

Gotchas...

Spelling Grammar Punctuation Tone Word choice Possessives Run-on sentences Unclear pronoun reference Verb agreement and tense

Gotchas… Spelling Keep a dictionary handy Proof-read and suspect Confusing words with similar spellings

affect effect allude elude discreet discrete its it’s principal principle

Unusual plurals analysis analyses phenomenon phenomena criterion criteria

American or English?

18

Gotchas… Grammar, Idiom, ...

My program has few bugs. (Ans to Ques: Does your program have many bugs?) My program has a few bugs. (Ans to Ques: Doesn’t your program have any bugs?)

Additional code to do internal sort has to be added. I am weighing 60 kilos. Here I am attaching the code that works for me. This is the kind of problem I faced when I am working on the AIX

environment. After entering the Bind DN and Password, the query wizard starts

which is not happening at your end. 19

Gotchas… Punctuation

If you are ill you ought to see a doctor. The book that I borrowed from you, is excellent. She was late for class, because her alarm clock was

broken. You have these three rooms for yourselves also you may

use the bathroom, whenever it is free.

20

Gotchas… Tone

Have removed the changes from main branch. Put it in be3 instead. I am checking to see if any other files have been inadvertently checked into main/Latest instead of be3.

The data set definition doesn't get propagated if I try to use the option 'Propagate Dataset Definition' in the GUI (Build 162). Is it a known bug or has it been fixed after Build 162?

21

Gotchas… Word choice

When a photon in that energy range strikes the atom, the atom (looses, loses) one of its outer electrons.

The talk centered (around, on) the (principal, principle) of virtual work.

We then sent the broken part to John Brooks, (who, whom) the laser group had recommended.

22

Gotchas… Possessives

This section explains the function of each technique and describes (its / it's / its') advantages and disadvantages.

Since 1981, when the air traffic (controller's / controllers') strike occurred, the number of controllers decreased from 16,200 to 14,300 [Krasner, 1997].

23

Gotchas… Run-on sentences

Both designs produce the same three outputs (x coordinate, y coordinate, and z coordinate) in roughly the same fashion, therefore, both designs have similar effects on the performance.

At that point the shock sphere is no longer strong enough to heat the air to incandescence, however, the sphere is still very strong.

24

Gotchas… Unclear pronoun reference

Although design flaws in the Titanic were realized soon after its sinking in 1912, the reasons for the severe damage inflicted by the iceberg remained a mystery until its discovery in 1985.

25

Gotchas… Verb agreement and tense

In the past three months, a new series of low-priced computers (has been released, have been released, released).

The most important design criteria is performance.

26

Conclusion

The key to successful technical writing is effectively structuring the document Where to begin How to organize How much detail to give

For successful language in technical writing, you have to balance precision with clarity Needless complex sentences misdirect readers

Besides casting your ideas in clear sentences, you have to connect those ideas Smooth flow of information across paragraph is a must

27

References

http://www.eecs.qmul.ac.uk/~norman/papers/good_writing/Technical%20writing_ver_5_2.pdf

28

THANK YOU

29