A Documentation Talk

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