A Documentation Talk

78b475797a14c84799063c7cd073962f?s=47 Zach Holman
September 02, 2011

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.

78b475797a14c84799063c7cd073962f?s=128

Zach Holman

September 02, 2011
Tweet

Transcript

  1. a documentation talk zach holman

  2. documentation is fucking important™

  3. @holman

  4. None
  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

  13. None
  14. @mojombo

  15. step one: README

  16. step two: trolololololol

  17. Your user interface is always the most important.

  18. None
  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

  28. None
  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