$30 off During Our Annual Pro Sale. View Details »

Documentation is freaking awesome

Kyle Neath
February 08, 2011

Documentation is freaking awesome

I have a confession: I love documentation — and I don't just mean code comments. I mean documentation of every form. I want to introduce you to the breadth of documentation styles and forms. I want to show you how to produce beautiful generated documentation. I want to explain what makes an awesome README. How to build an amazing marketing website for your library. I want to gush about why I think writing TomDoc is going to make you write better code.

Ruby is such an expressive language that your code can end up looking like anything you can imagine. Documentation is paramount in helping others understand why and how they should be using your code.

Kyle Neath

February 08, 2011
Tweet

More Decks by Kyle Neath

Other Decks in Programming

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