Post on 18-Nov-2014
description
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).
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
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