Documentation is freaking awesome

5f2da528927a2ec9ba4fec2069cbc958?s=47 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.

5f2da528927a2ec9ba4fec2069cbc958?s=128

Kyle Neath

February 08, 2011
Tweet

Transcript

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

  2. Kyle Neath is...

  3. ~designer @

  4. @kneath

  5. warpspire.com

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

  7. There’s a library for almost everything

  8. It’s not if the library exists... It’s whether I can

    figure out how to use the @!&*# thing
  9. Documentation is...

  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
  11. First there was RDoc rdoc.sourceforge.net “latest via CVS”

  12. None
  13. None
  14. Then there was YARD yardoc.org

  15. None
  16. And of course TomDoc tomdoc.org

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

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

  19. YARD & RDoc are highly structured

  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
  21. TomDoc is lightly structured

  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
  23. Also, tools like docco rocco, pycco, shocco

  24. None
  25. None
  26. None
  27. Code comments are just the start

  28. WEBSITE AN AWESOME

  29. Does your project Google?

  30. None
  31. What it does

  32. Getting Started What it does

  33. How to Contribute Getting Started What it does

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

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

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

    Started What it does
  37. (plus, it’s pretty)

  38. Great place to post long form tutorials

  39. None
  40. README AN AWESOME

  41. First Contact

  42. Elements of a great README

  43. Description Installation Instructions Links to more Docs How to Contribute

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

  45. MAN PAGES LOTS AND LOTS OF

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

  47. Documentation for UNIX tools (command line programs)

  48. ~$ man rails

  49. Many sections ~$ man 5 mustache

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

  51. BIG CAVEAT gems don’t install man pages :( check out

    gem-man until then
  52. Documentation is...

  53. CODE COMMENTS Available with the source Great for Contributors

  54. AWESOME WEBSITE Google Juice Command center for docs

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

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

    nerds look
  57. A Great Marketing Tool Documentation is...

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

  59. More Docs = Better Perceived Quality

  60. More Docs = Easier To Learn

  61. More Docs = Easier To Contribute

  62. tldr; More People Using Your Project

  63. “Top ten reasons why I wont use your open source

    project” Wynn Netherland pengwynn
  64. You don’t have a friggin’ Readme REASON #1

  65. You have no project home page REASON #3

  66. Documentation is important marketing

  67. Therapeutic Documentation is...

  68. Forces you to slow down

  69. Puts you into a different mindset

  70. Forces you to question your code

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

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

    just sucks
  73. Knowing how someone feels about code is valuable # XXX:

    I hate myself and want to die. # --rtomayko 2010-05-27
  74. At the end of the day... Writing documentation produces higher

    quality code
  75. Hacks & Tools Documentation

  76. rdoc.info Automatic YARD Generation

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

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

  79. gem server Locally Generated RDoc

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

  81. railsapi.com Downloadable Combines Multiple Docs

  82. railsapi.com Downloadable Combines Multiple Docs

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

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

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

  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
  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
  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
  89. None
  90. Final Thoughts

  91. Documentation is a lot more than RDoc

  92. Documenting should be something you want to do ProTip: It’s

    not a guilt trip
  93. Documenting is a great marketing tool

  94. Documenting helps you write better code

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

  96. Fin. warpspire.com/talks/documentation