update readme with more godog details

README.md

@@ -9,6 +9,13 @@ describe a feature of your application and how it should work, and only then imp
 
 The project is inspired by [behat][behat] and [cucumber][cucumber] and is based on cucumber [gherkin specification][gherkin].
 
+**Godog** does not intervene with the standard **go test** command and it's behavior. You can leverage both frameworks
+to functionally test your application while maintaining all test related source code in **_test.go** files.
+
+**Godog** acts similar compared to **go test** command. It builds all package sources to a single main package file
+and replaces **main** func with it's own and runs the build to test described application behavior in feature files.
+Production builds remains clean without any overhead.
+
 ### Install
 
     go get github.com/DATA-DOG/godog/cmd/godog

gherkin/README.md

@@ -10,6 +10,29 @@ creates an AST tree of gherkin Tokens read from the file.
 With gherkin language you can describe your application behavior as features in
 human-readable and machine friendly language.
 
+``` go
+package main
+
+import (
+	"log"
+	"os"
+
+	"github.com/DATA-DOG/godog/gherkin"
+)
+
+func main() {
+	feature, err := gherkin.ParseFile("ls.feature")
+	switch {
+	case err == gherkin.ErrEmpty:
+		log.Println("the feature file is empty and does not describe any feature")
+		return
+	case err != nil:
+		log.Fatalln("the feature file is incorrect or could not be read:", err)
+	}
+	log.Println("have parsed a feature:", feature.Title, "with", len(feature.Scenarios), "scenarios")
+}
+```
+
 ### Documentation
 
 See [godoc][godoc].

godog.go

@@ -3,6 +3,15 @@ Package godog is a behavior-driven development framework, a tool to describe you
 application based on the behavior and run these specifications. The features are
 described by a human-readable gherkin language.
 
+Godog does not intervene with the standard **go test** command and it's behavior.
+You can leverage both frameworks to functionally test your application while
+maintaining all test related source code in **_test.go** files.
+
+Godog acts similar compared to "go test" command. It builds all package sources
+to a single main package file and replaces main func with it's own and runs the
+build to test described application behavior in feature files.
+Production builds remains clean without any overhead.
+
 For example, imagine you’re about to create the famous UNIX ls command.
 Before you begin, you describe how the feature should work, see the example below..
 
@@ -16,8 +25,8 @@ Example:
 		Given I am in a directory "test"
 		And I have a file named "foo"
 		And I have a file named "bar"
-		When I run "ls"
-		Then I should get:
+		When I run ls
+		Then I should get output:
 		  """
 		  bar
 		  foo