Technical Writing 101

Elizabeth Naramore
Dutch PHP Conference
June, 2010

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
 This talk will:
Help you with the writing process
Help you improve your own writing
Point you to references for the future

6
This talk pertains to:
Blog posts
Articles
Technical books
Documentation (end-user, dev)

7
Why do we write?
Money
Fame
To improve our own knowledge
To help other people

8
Why do we write?
Money (meh.)
Fame (meh.)
To improve our own knowledge
To help other people

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
Where do we get ideas?

Problems you've solved (how-to)

15
Where do we get ideas?

Problems you've solved (how-to)

People you've met (interview)

16
Where do we get ideas?
Problems you've solved (how-to)
People you've met (interview)
New things you've tried (opinion)

17
Where do we get ideas?
Problems you've solved (how-to)
People you've met (interview)
New things you've tried (opinion)
Research you've done (news)

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
 Choose words wisely.
The difference between the right word
and the almost right word is the difference
between lightning and the lightning bug.
- Mark Twain

36
Simplify.

37
 Simplify.
The specimen of the canine species consumed
the edible substance belonging to him.

38
 Simplify.
The specimen of the canine species consumed
the edible substance belonging to him.

versus

The dog ate his food.

39
Keep paragraphs small
(but not too small).

Good estimate is
5-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
Think like your reader.

Empathy: Identification with and

understanding of
another's situation, feelings, and motives.

45
 Let's do
a 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 things
only seem like a
good 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
 Find your own style.

(Hopefully, it's somewhere between these two.)

59
Don't lose the human element.

Why's (Poignant) Guide to Ruby

60
Writing is not a
contest or a race.

61
You are the only one
that can share
what you know.

62
 RECAP
Idea.
Pre-write.
Write.
Edit & De-suckify.
Repeat.
63
This looks familiar.

64
 RECAP
Software 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
elizabeth@naramore.net
Freenode 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