Discussion on: Do you put examples/ directory with sample code for integrating your library?

This is one of the really nice things about Go.

It has built in support for examples in the testing framework. blog.golang.org/examples

So you can put stuff like this in your code

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}

And they will automatically appear in the documentation.

Example

The advantage of this over textual documentation (which often diverges from reality) is it is checked to be syntactically correct by the compiler and checked that it actually does what it says it does by running it as a test.