Documentation is freaking awesome

Transcript

1. FREAKING
   AWESOME
   DOCUMENTATION IS
   a magical afternoon with Kyle Neath
   

   View Slide

2. Kyle Neath is...
   

   View Slide

3. ~designer
   @
   

   View Slide

4. @kneath
   

   View Slide

5. warpspire.com
   

   View Slide

6. A favorite pastime...
   Building small projects
   with ruby
   

   View Slide

7. There’s a library for
   almost everything
   

   View Slide

8. It’s not if the library exists...
   It’s whether I can
   figure out how to use
   the @!&*# thing
   

   View Slide

9. Documentation is...
   

   View Slide

10. #########################################################################
    #
    # Tags
    #
    #########################################################################
    # Extract all tags into the tagmap and replace with placeholders.
    #
    # data - The raw String data.
    #
    # Returns the placeholder'd String data.
    def extract_tags(data)
    data.gsub(/(.?)\[\[(.+?)\]\]([^\[]?)/m) do
    if $1 == "'" && $3 != "'"
    "[[#{$2}]]#{$3}"
    elsif $2.include?('][')
    $&
    else
    id = Digest::SHA1.hexdigest($2)
    @tagmap[id] = $2
    "#{$1}#{id}#{$3}"
    end
    end
    end
    # Process all tags from the tagmap and replace the placeholders with the
    # final markup.
    CODE
    COMMENTS
    

    View Slide

11. First there was RDoc
    rdoc.sourceforge.net
    “latest via CVS”
    

    View Slide

12. View Slide

13. View Slide

14. Then there was YARD
    yardoc.org
    

    View Slide

15. View Slide

16. And of course TomDoc
    tomdoc.org
    

    View Slide

17. FACT
    TomDoc will save the world
    Photo Credit: Claude Nix
    

    View Slide

18. Unless you want
    generated docs
    Photo Credit: Claude Nix
    

    View Slide

19. YARD & RDoc are
    highly structured
    

    View Slide

20. # Reverses the contents of a String or IO object.
    #
    # @param [String, #read] contents the contents to reverse
    # @return [String] the contents reversed lexically
    def reverse(contents)
    ...
    end
    

    View Slide

21. TomDoc is lightly
    structured
    

    View Slide

22. # Extract all code blocks into the codemap and replace
    # with placeholders.
    #
    # data - The raw String data.
    #
    # Returns the placeholder'd String data.
    def extract_code(data)
    ...
    end
    

    View Slide

23. Also, tools like docco
    rocco, pycco, shocco
    

    View Slide

24. View Slide

25. View Slide

26. View Slide

27. Code comments are
    just the start
    

    View Slide

28. WEBSITE
    AN AWESOME
    

    View Slide

29. Does your project
    Google?
    

    View Slide

30. View Slide

31. What it does
    

    View Slide

32. Getting Started
    What it does
    

    View Slide

33. How to
    Contribute
    Getting Started
    What it does
    

    View Slide

34. How to
    Contribute
    Bug Reports
    Getting Started
    What it does
    

    View Slide

35. How to
    Contribute
    Bug Reports
    More
    Documentation
    Getting Started
    What it does
    

    View Slide

36. Multiple Versions
    How to
    Contribute
    Bug Reports
    More
    Documentation
    Getting Started
    What it does
    

    View Slide

37. (plus, it’s pretty)
    

    View Slide

38. Great place to post
    long form tutorials
    

    View Slide

39. View Slide

40. README
    AN AWESOME
    

    View Slide

41. First Contact
    

    View Slide

42. Elements of a great
    README
    

    View Slide

43. Description
    Installation Instructions
    Links to more Docs
    How to Contribute
    Credits, Alternatives
    

    View Slide

44. Think about writing
    your README first
    (readme driven development)
    

    View Slide

45. MAN PAGES
    LOTS AND LOTS OF
    

    View Slide

46. WTF is a
    man page?
    Photo Credit: Tom Preston-Werner
    

    View Slide

47. Documentation for
    UNIX tools
    (command line programs)
    

    View Slide

48. ~$ man rails
    

    View Slide

49. Many sections
    ~$ man 5 mustache
    

    View Slide

50. mustache(5) - Mustache Syntax
    mustache(1) - Usage of `mustache`
    

    View Slide

51. BIG CAVEAT
    gems don’t install man
    pages :(
    check out gem-man until then
    

    View Slide

52. Documentation is...
    

    View Slide

53. CODE COMMENTS
    Available with the source
    Great for Contributors
    

    View Slide

54. AWESOME WEBSITE
    Google Juice
    Command center for docs
    

    View Slide

55. AWESOME README
    Available with the source
    First contact with docs
    

    View Slide

56. LOTS OF MAN PAGES
    Available in terminal
    First place UNIX nerds look
    

    View Slide

57. A Great
    Marketing Tool
    Documentation is...
    

    View Slide

58. First contact with your
    project
    (make it count!)
    

    View Slide

59. More Docs
    =
    Better Perceived Quality
    

    View Slide

60. More Docs
    =
    Easier To Learn
    

    View Slide

61. More Docs
    =
    Easier To Contribute
    

    View Slide

62. tldr;
    More People Using Your
    Project
    

    View Slide

63. “Top ten reasons why I
    wont use your open
    source project”
    Wynn Netherland
    pengwynn
    

    View Slide

64. You don’t have a
    friggin’ Readme
    REASON #1
    

    View Slide

65. You have no project
    home page
    REASON #3
    

    View Slide

66. Documentation is
    important marketing
    

    View Slide

67. Therapeutic
    Documentation is...
    

    View Slide

68. Forces you to
    slow down
    

    View Slide

69. Puts you into a
    different mindset
    

    View Slide

70. Forces you to
    question your code
    

    View Slide

71. Explaining code often
    reveals flaws
    (like an invisible pairing partner)
    

    View Slide

72. It can also be a great
    stress reliever
    sometimes code just sucks
    

    View Slide

73. Knowing how
    someone feels about
    code is valuable
    # XXX: I hate myself and want to die.
    # --rtomayko 2010-05-27
    

    View Slide

74. At the end of the day...
    Writing documentation
    produces higher quality code
    

    View Slide

75. Hacks & Tools
    Documentation
    

    View Slide

76. rdoc.info
    Automatic YARD
    Generation
    

    View Slide

77. rdoc.info
    GitHub Integration
    (generate docs on push)
    

    View Slide

78. rdoc.info
    GitHub Integration
    (generate docs on push)
    

    View Slide

79. gem server
    Locally Generated RDoc
    

    View Slide

80. railsapi.com
    Awesome find-as-you-type
    Ruby/Rails/Gem Docs
    

    View Slide

81. railsapi.com
    Downloadable
    Combines Multiple Docs
    

    View Slide

82. railsapi.com
    Downloadable
    Combines Multiple Docs
    

    View Slide

83. railsapi
    +
    Fluid.app
    Awesome offline Ruby &
    Rails documentation
    

    View Slide

84. jqapi.com
    Like railsapi.com, but for
    jQuery
    

    View Slide

85. ronn
    Write man pages in
    markdown
    github.com/rtomayko/ronn
    

    View Slide

86. .br
    \fBronn\fR < \fIfile\fR
    .
    .SH "DESCRIPTION"
    \fBRonn\fR converts textfiles to standard roff\-
    formatted UNIX manpages or HTML\. ronn\-format(7) is
    based on markdown(7) but includes additional rules
    and syntax geared toward authoring manuals\.
    .
    man pages are written in roff
    

    View Slide

87. .br
    \fBronn\fR < \fIfile\fR
    .
    .SH "DESCRIPTION"
    \fBRonn\fR converts textfiles to standard roff\-
    formatted UNIX manpages or HTML\. ronn\-format(7) is
    based on markdown(7) but includes additional rules
    and syntax geared toward authoring manuals\.
    .
    man pages are written in roff
    but roff is dumb
    

    View Slide

88. ## DESCRIPTION
    **Ronn** converts textfiles to standard roff-
    formatted UNIX manpages or HTML. ronn-format(7) is
    based on markdown(7) but includes additional rules
    and syntax geared toward authoring manuals.
    use ronn instead
    Get HTML generation for free
    

    View Slide

89. View Slide

90. Final Thoughts
    

    View Slide

91. Documentation is a lot
    more than RDoc
    

    View Slide

92. Documenting should be
    something you want to do
    ProTip: It’s not a guilt trip
    

    View Slide

93. Documenting is a great
    marketing tool
    

    View Slide

94. Documenting helps you
    write better code
    

    View Slide

95. ... and always keep an offline
    version of your docs
    

    View Slide

96. Fin.
    warpspire.com/talks/documentation
    

    View Slide