README Driven Development: Testing libraries from a user perspective

What really is outside in testing when writing a library? I have seen different
approaches to this problem like cucumber, rspec or bacon, but one step that
seems to be missing in a lot of cases is testing what the user sees first, the
README. On Github the README file has really become the first thing any
developer coming in touch with a library looks at, so it should be the getting
started guide, and something that can make or break the experience a developer
has. But many developers including myself seem to face a problem so keeping the
documentation working and updated. This got me thinking what I really want in
there are code samples, and those code samples should work copy and paste.

To achieve this the README has to be part of my build process, so I started
experimenting with including a runner for code inside as a Rake task

https://gist.github.com/sideshowcoder/8358021.js

The Idea really is nothing new, but I have been struggling to find a well
integrated solution. This is probably the simplest solution I could come up
with. I’m currently driving the development of a library idea for my talk at
takeoffconf, and it allows me to really focus on
the concept of the code from a user perspective writing the README first and
building the working code from there on.

Currently the solution is not robust so any help is greatly appreciated, even
though for now it works.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s