Technical Writing 101 Elizabeth Naramore Dutch PHP Conference - - PowerPoint PPT Presentation

▶
technical writing 101
SMART_READER_LITE
LIVE PREVIEW

Technical Writing 101 Elizabeth Naramore Dutch PHP Conference - - PowerPoint PPT Presentation

Jun 22, 2023 135 likes •808 views

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

slide-1
SLIDE 1

Elizabeth Naramore Dutch PHP Conference June, 2010

Technical Writing 101

1

slide-2
SLIDE 2

ATTENTION.

2

slide-3
SLIDE 3

THERE IS NO CODE HERE.

3

slide-4
SLIDE 4

THIS IS A SOFT SKILLS TALK.

4

slide-5
SLIDE 5

THIS IS A SOFT SKILLS TALK.

(It's not just fluff, but will make you a stronger, more well-rounded developer.) 5

slide-6
SLIDE 6

Help you with the writing process Help you improve your own writing Point you to references for the future

This talk will:

6

slide-7
SLIDE 7

Blog posts Articles Technical books Documentation (end-user, dev)

This talk pertains to:

7

slide-8
SLIDE 8

Money Fame To improve our own knowledge To help other people

Why do we write?

8

slide-9
SLIDE 9

Money (meh.) Fame (meh.) To improve our own knowledge To help other people

Why do we write?

9

slide-10
SLIDE 10

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

10

slide-11
SLIDE 11

A lot of this out there.

(Let's deflate it.)

11

slide-12
SLIDE 12

READY?

12

slide-13
SLIDE 13

An idea.

13

slide-14
SLIDE 14

No ideas?

14

slide-15
SLIDE 15

Problems you've solved (how-to)

Where do we get ideas?

15

slide-16
SLIDE 16

Problems you've solved (how-to) People you've met (interview)

Where do we get ideas?

16

slide-17
SLIDE 17

Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion)

Where do we get ideas?

17

slide-18
SLIDE 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

slide-19
SLIDE 19
  • 1. PRE-WRITE.

19

slide-20
SLIDE 20

Coredump.

20

slide-21
SLIDE 21

Use cubing.

21

slide-22
SLIDE 22

Side 1: Describe.

22

slide-23
SLIDE 23

Side 2: Compare.

23

slide-24
SLIDE 24

Side 3: Associate.

24

slide-25
SLIDE 25

Side 4: Analyze.

25

slide-26
SLIDE 26

Side 5: Apply.

26

slide-27
SLIDE 27

Side 6: Argue.

27

slide-28
SLIDE 28

Sort and outline.

28

slide-29
SLIDE 29

Plug holes with research.

29

slide-30
SLIDE 30
  • 2. WRITE.

30

slide-31
SLIDE 31
  • 3. EDIT.

(Make it not suck.)

31

slide-32
SLIDE 32

First, the easy-ish stuff.

32

slide-33
SLIDE 33

Respect the rules

  • f the language.

33

slide-34
SLIDE 34

Check your facts.

34

slide-35
SLIDE 35

“I believe more in the scissors than I do in the pencil.”

  • Truman Capote

35

slide-36
SLIDE 36

“The difference between the right word and the almost right word is the difference between lightning and the lightning bug.”

  • Mark Twain

Choose words wisely.

36

slide-37
SLIDE 37

Simplify.

37

slide-38
SLIDE 38

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

Simplify.

38

slide-39
SLIDE 39

The specimen of the canine species consumed the edible substance belonging to him. versus The dog ate his food.

Simplify.

39

slide-40
SLIDE 40

Keep paragraphs small (but not too small).

Good estimate is 5-6 sentences

40

slide-41
SLIDE 41

Second, the not so easy-ish stuff.

41

slide-42
SLIDE 42

Clear logic. Clear writing.

42

slide-43
SLIDE 43

Keep the flow going.

43

slide-44
SLIDE 44

Don't dilute your message.

44

slide-45
SLIDE 45

Empathy: Identification with and understanding of another's situation, feelings, and motives.

Think like your reader.

45

slide-46
SLIDE 46

Let's do a cheesy exercise.

46

slide-47
SLIDE 47

47

slide-48
SLIDE 48

48

slide-49
SLIDE 49

49

slide-50
SLIDE 50

End result:

Right?

50

slide-51
SLIDE 51

If you don't tell me, I don't know.

51

slide-52
SLIDE 52

STOP. (We're not quite done yet.)

52

slide-53
SLIDE 53

Read it aloud. Does it flow?

53

slide-54
SLIDE 54

Elicit a second

  • pinion.

(Some things

  • nly seem like a

good idea.)

54

slide-55
SLIDE 55

More stuff to remember.

55

slide-56
SLIDE 56

Bad writing is easy. Bad writing makes reading hard.

56

slide-57
SLIDE 57

Good writing is hard. Good writing makes reading easy.

57

slide-58
SLIDE 58

Practice makes perfect.

58

slide-59
SLIDE 59

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

Find your own style.

59

slide-60
SLIDE 60

Why's (Poignant) Guide to Ruby

Don't lose the human element.

60

slide-61
SLIDE 61

Writing is not a contest or a race.

61

slide-62
SLIDE 62

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

62

slide-63
SLIDE 63

RECAP Idea. Pre-write. Write. Edit & De-suckify. Repeat.

63

slide-64
SLIDE 64

This looks familiar.

64

slide-65
SLIDE 65

RECAP Software Requirements. Planning & Testing. Coding. Refactoring. Repeat.

65

slide-66
SLIDE 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

slide-67
SLIDE 67

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