technical writing 101
TRANSCRIPT
Elizabeth NaramoreDutch PHP Conference
June, 2010
Technical Writing 101
1
ATTENTION.
2
THERE IS NO CODE HERE.
3
THIS IS A SOFT SKILLS
TALK.
4
THIS IS A SOFT SKILLS
TALK.(It's not just fluff, but will
make you a stronger,more well-rounded developer.)
5
Help you with the writing process Help you improve your own writing Point you to references for the future
This talk will:
6
Blog posts Articles Technical books Documentation (end-user, dev)
This talk pertains to:
7
Money Fame To improve our own knowledge To help other people
Why do we write?
8
Money (meh.) Fame (meh.) To improve our own knowledge To help other people
Why do we write?
9
You are the only one that can share
what you know.
10
A lot of this out there.
(Let's deflate it.)11
READY?
12
An idea.
13
No ideas?
14
Problems you've solved (how-to)
Where do we get ideas?
15
Problems you've solved (how-to) People you've met (interview)
Where do we get ideas?
16
Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion)
Where do we get ideas?
17
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
1. PRE-WRITE.
19
Coredump.
20
Use cubing.
21
Side 1: Describe.
22
Side 2: Compare.
23
Side 3: Associate.
24
Side 4: Analyze.
25
Side 5: Apply.
26
Side 6: Argue.
27
Sort and outline.
28
Plug holes with research.
29
2. WRITE.
30
3. EDIT.(Make it not suck.)
31
First,the easy-ish stuff.
32
Respect the rules of the language.
33
Check your facts.
34
“I believe more in the scissors than I do in the pencil.”
- Truman Capote
35
“The difference between the right wordand the almost right word is the differencebetween lightning and the lightning bug.”
- Mark Twain
Choose words wisely.
36
Simplify.
37
The specimen of the canine species consumed the edible substance belonging to him.
Simplify.
38
The specimen of the canine species consumed the edible substance belonging to him.
versus
The dog ate his food.
Simplify.
39
Keep paragraphs small(but not too small).
Good estimate is5-6 sentences
40
Second,the not so easy-ish stuff.
41
Clear logic. Clear writing.
42
Keep the flow going.
43
Don't dilute your message.
44
Empathy: Identification with and understanding of
another's situation, feelings, and motives.
Think like your reader.
45
Let's doa cheesy exercise.
46
47
48
49
End result:
Right?50
If you don't tell me, I don't know.
51
STOP.
(We're not quite done yet.)
52
Read it aloud.
Does it flow?
53
Elicit a second opinion.
(Some thingsonly seem like agood idea.)
54
More stuff to remember.
55
Bad writing is easy.
Bad writing makes reading hard.
56
Good writing is hard.
Good writing makes reading easy.
57
Practice makes perfect.
58
(Hopefully, it's somewhere between these two.)
Find your own style.
59
Why's (Poignant) Guide to Ruby
Don't lose the human element.
60
Writing is not a contest or a race.
61
You are the only one that can share
what you know.
62
RECAPIdea.Pre-write.Write.Edit & De-suckify.Repeat.
63
This looks familiar.
64
RECAPSoftware Requirements.Planning & Testing.Coding.Refactoring.Repeat.
65
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
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