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.

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”
14. Then there was YARD yardoc.org
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
27. Code comments are just the start
28. WEBSITE AN AWESOME
29. Does your project Google?
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
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
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