Writing technically

Writing Technically

Muhammad Hassan NasrTeam LeaderBadrIT

Technical Writing

What is it anyway?

Its About Technical communication.

Why Technical Writing?

First Thing:Its how you look to others

Clients, Manager, Professor, ...

They rarely see your code or work details

But

They do read your mails,...

Documentation

Presentations,Reports, API Docs, ...

Installation Guide, User Guide, Help, etc.

Second Thing:It isn't how good you

are...

It's how you are communicating your

good work !

Third Thing:

Your work will be useless if others can't understand you

First Impressions Last

So, How to be a good technical writer?

And even a good communicator...

Three C's

Clear

Know your audience

Talk their language

Use jargon they know

Define the unfamiliar

The weather was of an extreme nature on the

west coast.

Can we rewrite the above?

California had very cold weather last week.

Concise

Keep it Simple, Stupid (KISS)

Less is More

That is something with which I cannot agree.

Can we rewrite the above?

That is something I cannot agree with.

Complete

Say what you should and no more.

Give references, wiki links, ...

OK, lets learn how to write..

Writing is layout + letters

Let's look at the layout.

Technical Writing is Presentational

Attractive Layout

Top Down Strategy

Headings

Chunks"Short Paragraphs"

Use Images

A picture is worth a thousand words

Use examples

Examples eliminate misconceptions

Now let's play with the letters

Start with capital

End with a period.

Other examples of period

Dr. Bauer M.S. degree

Steven S. Wilson Jr.(Time is now 4:30 p.m.)

(10 B.C.)

Use commas, semicolon and other punctuations.

after the show ended.we had coffee

What is wrong with the above?

After the show ended, we had coffee.

You will need to do more homework; for example read rules here and here

This is an example of colon:● Some bullets.● It can be followed a

numbered.● Or alpha list as well.

Bullets and numbered list make your info clear and

absorbable.

What's wrong with this?

Use only 1 space between words

"Don't forget to use Quotations", Muhammad

Hassan said.

Use parentheses to make it more clear (this is a recursive example).

Apostrophe have it's rules isn't that true?

Hyphen is a bit-tricky

Use spell-checker or google to validate

Why i use JAVA to access api?.

What's wrong with the above?

Why i use JAVA to access api?.

The pronoun i can't ever be small.

All capital letters meansAbbreviation (API)

orSHOUTING

No capitals in the middle.

Except for...

● Titles: Writing Technically● Knowns: Thursday, Sun,

Alex, East ... ● Proper Nouns: Testing Team● Names: Muhammad Hassan

More rules here

One last thing ...

Writing Process

Similar to software process

Prewriting

Drafting

Revising

Structure, Spell and grammar check

Read it through the eye of your audience

Editing

Let's recap

Others see you through your writings

ClearConcise

Complete

Writing = layout + letters

Writing Process

Homework

Employee: Complete learning

Management: Update Evaluation

Process

References

● Wikipedia● Sentence Structure of Technical Writing● Writing Process● Top 10 rules of punctuation.● Effective Writing● Capitalization Rules● Punctuation Rules

To be a good writer, read a lot of good text.

Thanks