Documentation is freaking awesome

Download the presentation (6MB PDF)

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.

References

Documentation Formats

• RDoc
• YARD
• TomDoc
  • TomDoc.rb
• docco
  • rocco
  • shocco
  • pycco

Good Website Examples

• Bundler
• libgit2
• Modernizer
• CofeeeScript
• Rails Guides

READMEs

• Readme driven development

Man pages

• mustache(1)
• mustache(5)
• gem-man

Hacks & Tools

• rdoc.info – Automatically generate RDoc/YARD from a GitHub webhook.
• railsapi.com – Ruby/Rails/(Some)Gems find-as-you-type downloadable documentation.
• jqapi.com – jQuery find-as-you-type downloadable documentation.
• Fluid.app – Put HTML docs in your Dock.
• ronn – Write man pages in markdown

Misc

• Top ten reasons why I won’t use your open source project

You should probably follow @kneath on twitter

You’re sure to learn all kinds of interesting facts about cheese, BBQ and perhaps even some ramblings on design, tech and the wonderful internets.