Slide 1

Slide 1 text

a documentation talk zach holman

Slide 2

Slide 2 text

documentation is fucking important™

Slide 3

Slide 3 text

@holman

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

#zomg_zach_holmans_talk_ is_so_amazing_i_am_really_ impressed_by_his_awesome _talk_you_should_follow_him _on_twitter_because_he_has _dreamy_eyes

Slide 6

Slide 6 text

when are we drinking?

Slide 7

Slide 7 text

why should we do this shit?

Slide 8

Slide 8 text

I hate documentation. I hate process. I hate helping anyone.

Slide 9

Slide 9 text

documentation should be selfish

Slide 10

Slide 10 text

ruby IMPROVE YOUR tests ......F... .....F.... F......... projects

Slide 11

Slide 11 text

projects

Slide 12

Slide 12 text

readme-driven development

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

@mojombo

Slide 15

Slide 15 text

step one: README

Slide 16

Slide 16 text

step two: trolololololol

Slide 17

Slide 17 text

Your user interface is always the most important.

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

on GitHub, READMEs work in subdirectories, too.

Slide 20

Slide 20 text

Everyone loves a good README.

Slide 21

Slide 21 text

NoMethodError: undefined method `tonight' for # in `am_i_intoxicated?'

Slide 22

Slide 22 text

def am_i_intoxicated? amount_drank(me.bar_tab)[2].tonight end

Slide 23

Slide 23 text

def amount_drank(tab) [ milk, water, whisky(tab)] end

Slide 24

Slide 24 text

def whisky(tab) WhiskyAnalysis.analyze(tab) end

Slide 25

Slide 25 text

module WhiskyAnalysis def self.fuuuuuuuuuuuuuuuuuuuuuuu

Slide 26

Slide 26 text

You shouldn’t need to reconstruct entire chains of methods mentally.

Slide 27

Slide 27 text

inline documentation

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

TomDoc Tom Preston-Werner, creator

Slide 30

Slide 30 text

def add_mustache(image) end

Slide 31

Slide 31 text

# Public: This adds a mustache to an image. # # image - A String path to a local image on disk. # # Examples # # add_mustache(‘~/Desktop/zach.gif’) # # => ‘/tmp/zach.mustache.gif’ # # Returns the String path to the processed image. def add_mustache(image) end

Slide 32

Slide 32 text

# Public: This adds a mustache to an image. # # image - A String path to a local image on disk. # # Examples # # add_mustache(‘~/Desktop/zach.gif’) # # => ‘/tmp/zach.mustache.gif’ # # Returns the String path to the processed image. def add_mustache(image) end

Slide 33

Slide 33 text

# Public: This adds a mustache to an image. # # image - A String path to a local image on disk. # # Examples # # add_mustache(‘~/Desktop/zach.gif’) # # => ‘/tmp/zach.mustache.gif’ # # Returns the String path to the processed image. def add_mustache(image) end

Slide 34

Slide 34 text

# Public: This adds a mustache to an image. # # image - A String path to a local image on disk. # # Examples # # add_mustache(‘~/Desktop/zach.gif’) # # => ‘/tmp/zach.mustache.gif’ # # Returns the String path to the processed image. def add_mustache(image) end

Slide 35

Slide 35 text

# Public: This adds a mustache to an image. # # image - A String path to a local image on disk. # # Examples # # add_mustache(‘~/Desktop/zach.gif’) # # => ‘/tmp/zach.mustache.gif’ # # Returns the String path to the processed image. def add_mustache(image) end

Slide 36

Slide 36 text

plaintext explicit english flexible

Slide 37

Slide 37 text

ruby

Slide 38

Slide 38 text

TINY METHODS

Slide 39

Slide 39 text

SMARTER METHODS

Slide 40

Slide 40 text

tests ......F... .....F.... F.........

Slide 41

Slide 41 text

KNOW YOUR INPUT & OUTPUT

Slide 42

Slide 42 text

KNOW YOUR EDGE CASES

Slide 43

Slide 43 text

GitHub TomDocs its Ruby JavaScript Shell CoffeeScript C Erlang

Slide 44

Slide 44 text

hating on tomdoc

Slide 45

Slide 45 text

“My code is perfect.”

Slide 46

Slide 46 text

“No one updates documentation.”

Slide 47

Slide 47 text

“It’s too verbose.”

Slide 48

Slide 48 text

“My commit messages, tests, and/or my left bicep tattoos are my docs.”

Slide 49

Slide 49 text

Thanks.

Slide 50

Slide 50 text

@holman