add an example in readme

README.md

@@ -20,6 +20,98 @@ Production builds remains clean without any overhead.
 
     go get github.com/DATA-DOG/godog/cmd/godog
 
+### Example
+
+Imagine we have a **godog cart** to serve godogs for dinner. At first, we describe our feature:
+
+``` gherkin
+# file: /tmp/godog/godog.feature
+Feature: eat godogs
+  In order to be satiated
+  As an user
+  I need to be able to eat godogs
+
+  Scenario: Eat 5 out of 12
+    Given there are 12 godogs
+    When I eat 5
+    Then there should be 7 remaining
+```
+
+As a developer, your work is done as soon as you’ve made the program behave as
+described in the Scenario.
+
+If you run `godog godog.feature` inside the **/tmp/godog** directory.
+You should see that the steps are undefined:
+
+![Screenshot](https://raw.github.com/DATA-DOG/godog/master/screenshots/undefined.png)
+
+``` go
+/* file: /tmp/godog/godog.go */
+package main
+
+type GodogCart struct {
+	reserve int
+}
+
+func (c *GodogCart) Eat(num int) { c.reserve -= num }
+
+func (c *GodogCart) Available() int { return c.reserve }
+
+func main() { /* usual main func */ }
+```
+
+If you run `godog godog.feature` inside the **/tmp/godog** directory.
+You should see that the steps are undefined.
+
+Now lets describe all steps to test the application behavior:
+
+``` go
+/* file: /tmp/godog/godog_test.go */
+package main
+
+import (
+	"fmt"
+
+	"github.com/DATA-DOG/godog"
+	"github.com/DATA-DOG/godog/gherkin"
+)
+
+func (c *GodogCart) resetReserve(*gherkin.Scenario) {
+	c.reserve = 0
+}
+
+func (c *GodogCart) thereAreNumGodogsInReserve(args ...*godog.Arg) error {
+	c.reserve = args[0].Int()
+	return nil
+}
+
+func (c *GodogCart) iEatNum(args ...*godog.Arg) error {
+	c.Eat(args[0].Int())
+	return nil
+}
+
+func (c *GodogCart) thereShouldBeNumRemaining(args ...*godog.Arg) error {
+	if c.Available() != args[0].Int() {
+		return fmt.Errorf("expected %d godogs to be remaining, but there is %d", args[0].Int(), c.Available())
+	}
+	return nil
+}
+
+func godogCartContext(s godog.Suite) {
+	c := &GodogCart{}
+	// each time before running scenario reset reserve
+	s.BeforeScenario(c.resetReserve)
+	// register steps
+	s.Step(`^there are (\d+) godogs?$`, c.thereAreNumGodogsInReserve)
+	s.Step(`^I eat (\d+)$`, c.iEatNum)
+	s.Step(`^there should be (\d+) remaining$`, c.thereShouldBeNumRemaining)
+}
+```
+
+Now when you run the `godog godog.feature` again, you should see:
+
+![Screenshot](https://raw.github.com/DATA-DOG/godog/master/screenshots/passed.png)
+
 ### Documentation
 
 See [godoc][godoc] and [gherkin godoc][godoc_gherkin] for general API details.