Page 1
Elizabeth NaramoreDutch PHP Conference
June, 2010
Technical Writing 101
1
Page 3
THERE IS NO CODE HERE.
3
Page 4
THIS IS A SOFT SKILLS
TALK.
4
Page 5
THIS IS A SOFT SKILLS
TALK.(It's not just fluff, but will
make you a stronger,more well-rounded developer.)
5
Page 6
Help you with the writing process Help you improve your own writing Point you to references for the future
This talk will:
6
Page 7
Blog posts Articles Technical books Documentation (end-user, dev)
This talk pertains to:
7
Page 8
Money Fame To improve our own knowledge To help other people
Why do we write?
8
Page 9
Money (meh.) Fame (meh.) To improve our own knowledge To help other people
Why do we write?
9
Page 10
You are the only one that can share
what you know.
10
Page 11
A lot of this out there.
(Let's deflate it.)11
Page 15
Problems you've solved (how-to)
Where do we get ideas?
15
Page 16
Problems you've solved (how-to) People you've met (interview)
Where do we get ideas?
16
Page 17
Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion)
Where do we get ideas?
17
Page 18
Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion) Research you've done (news)
Where do we get ideas?
18
Page 22
Side 1: Describe.
22
Page 23
Side 2: Compare.
23
Page 24
Side 3: Associate.
24
Page 25
Side 4: Analyze.
25
Page 26
Side 5: Apply.
26
Page 27
Side 6: Argue.
27
Page 28
Sort and outline.
28
Page 29
Plug holes with research.
29
Page 31
3. EDIT.(Make it not suck.)
31
Page 32
First,the easy-ish stuff.
32
Page 33
Respect the rules of the language.
33
Page 34
Check your facts.
34
Page 35
“I believe more in the scissors than I do in the pencil.”
- Truman Capote
35
Page 36
“The difference between the right wordand the almost right word is the differencebetween lightning and the lightning bug.”
- Mark Twain
Choose words wisely.
36
Page 38
The specimen of the canine species consumed the edible substance belonging to him.
Simplify.
38
Page 39
The specimen of the canine species consumed the edible substance belonging to him.
versus
The dog ate his food.
Simplify.
39
Page 40
Keep paragraphs small(but not too small).
Good estimate is5-6 sentences
40
Page 41
Second,the not so easy-ish stuff.
41
Page 42
Clear logic. Clear writing.
42
Page 43
Keep the flow going.
43
Page 44
Don't dilute your message.
44
Page 45
Empathy: Identification with and understanding of
another's situation, feelings, and motives.
Think like your reader.
45
Page 46
Let's doa cheesy exercise.
46
Page 50
End result:
Right?50
Page 51
If you don't tell me, I don't know.
51
Page 52
STOP.
(We're not quite done yet.)
52
Page 53
Read it aloud.
Does it flow?
53
Page 54
Elicit a second opinion.
(Some thingsonly seem like agood idea.)
54
Page 55
More stuff to remember.
55
Page 56
Bad writing is easy.
Bad writing makes reading hard.
56
Page 57
Good writing is hard.
Good writing makes reading easy.
57
Page 58
Practice makes perfect.
58
Page 59
(Hopefully, it's somewhere between these two.)
Find your own style.
59
Page 60
Why's (Poignant) Guide to Ruby
Don't lose the human element.
60
Page 61
Writing is not a contest or a race.
61
Page 62
You are the only one that can share
what you know.
62
Page 63
RECAPIdea.Pre-write.Write.Edit & De-suckify.Repeat.
63
Page 64
This looks familiar.
64
Page 65
RECAPSoftware Requirements.Planning & Testing.Coding.Refactoring.Repeat.
65
Page 66
Need references for later?
Elements of Style by Strunk & White Pocket Book of Grammar for Engineers and Scientists NYT Manual of Style and Usage Merriam Webster's Punctuation and Style Dictionary of Misspelled Words
66
Page 67
Want to contact me?
http://naramore.net/blog@ElizabethN
[email protected] IRC: ElizabethN
THANKS!several images were used with permission from: - The awesome folks at Cheezburger Network (http://cheezburger.com/sites) - Matt Ballard (http://realitysideb.com)
67