Reading Rainbow: How to Read Code and Documentation

Short Form
Scheduled: Wednesday, June 27, 2012 from 2:30 – 3:15pm


One of the best methods for learning new coding techniques is to read open
source code. However, unlike normal books, code isn't meant to be read from
top to bottom, beginning to end. Instead, code is more like a
choose-your-own-adventure book, where each function can take you down a
different path. I'll highlight some well documented open source projects, what
makes them easy to get started for readers, and how to get started learning a
new technology. For veteran developers, this talk will point out common
pitfalls in documentation and how to avoid them for beginners.


Having worked on a wide variety of projects in different industries while
consulting with Intridea, I’ve seen a lot of time wasted onboarding developers
to new projects because of bad documentation. The same is true for open source
projects with patchy docs. In the talk, I want to go over best practices at a
high level with topics like:

  • How to explore code – in the console, in an isolated way
  • Project READMEs – what they’re for, what they should and should not include
  • Where and when to ask questions
  • How to ask good questions
  • Tests – how to read test code, and how to run them
  • Ticketing systems, wiki’s – what information to capture in them, how to write good reports
  • Code documentation – tools to generate (rdoc, yard), the separation between documentation and tutorials
  • Code samples – what they should showcase, how to make them visible in the project and easy to run

Speaking experience, This talk has not been given at another conference, but I have submitted it as a proposal for other conferences.


  • 648e730c3838a1b7c7839205932abeea

    Jerry Cheung



    Jerry Cheung splits his time as a co-founder of Opperator and a developer at
    Intridea. He is a co-author of the upcoming MacRuby in Action book, and likes
    contributing to open source. He’s currently dabbling in evented Ruby and Grape
    driven webapps. When he’s not coding, he stalks awesome cars in Southern
    California and writes about them in RockyRoadBlog.