A Documentation Talk

"A Documentation Talk" sounds pretty boring, right? Wouldn't it be scandalously titillating if this talk's title included detailed analysis of the expectations and results of the talk itself? Jeez it's like someone's making an overt metaphor for how Rubyists document their code.

At GitHub, we add docs to every single method we write, and we couldn't be more excited about it. It means faster and simpler code. It means stronger tests. It means your developers can pay attention to new commits without stressing about them. Documentation will make your project so very happy.

Transcript

1. a documentation talk zach holman
2. documentation is fucking important™
3. @holman
5. #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
6. when are we drinking?
7. why should we do this shit?
8. I hate documentation. I hate process. I hate helping anyone.
9. documentation should be selfish
10. ruby IMPROVE YOUR tests ......F... .....F.... F......... projects
11. projects
12. readme-driven development
14. @mojombo
15. step one: README
16. step two: trolololololol
17. Your user interface is always the most important.
19. on GitHub, READMEs work in subdirectories, too.
20. Everyone loves a good README.
21. NoMethodError: undefined method `tonight' for #<Object:0x1006e5180> in `am_i_intoxicated?'
22. def am_i_intoxicated? amount_drank(me.bar_tab)[2].tonight end
23. def amount_drank(tab) [ milk, water, whisky(tab)] end
24. def whisky(tab) WhiskyAnalysis.analyze(tab) end
25. module WhiskyAnalysis def self.fuuuuuuuuuuuuuuuuuuuuuuu
26. You shouldn’t need to reconstruct entire chains of methods mentally.
27. inline documentation
29. TomDoc Tom Preston-Werner, creator
30. def add_mustache(image) end
31. # 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
32. # 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
33. # 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
34. # 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
35. # 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
36. plaintext explicit english flexible
37. ruby
38. TINY METHODS
39. SMARTER METHODS
40. tests ......F... .....F.... F.........
41. KNOW YOUR INPUT & OUTPUT
42. KNOW YOUR EDGE CASES
43. GitHub TomDocs its Ruby JavaScript Shell CoffeeScript C Erlang
44. hating on tomdoc
45. “My code is perfect.”
46. “No one updates documentation.”
47. “It’s too verbose.”
48. “My commit messages, tests, and/or my left bicep tattoos are my docs.”
49. Thanks.
50. @holman