Update project docs and layout (open-telemetry#92)

* Update README and add README for instrumentation

Resolves open-telemetry#28

* Fix macaron instrumentation package name

* Update instrumentation README

Keep Go package docs in Go form.

* Update README

Add Contents of the repo section and link to CONTRIBUTING.md

* Fix relative replace for macaron

* Update README.md

Fix gitter link.

README.md

@@ -1,7 +1,17 @@
-# opentelemetry-go-contrib
+# OpenTelemetry-Go Contrib
 
-This repo contains packages that facilitate instrumenting commonly
-used libraries with OpenTelemetry for distributed tracing and
-monitoring.
+[![Circle CI](https://circleci.com/gh/open-telemetry/opentelemetry-go-contrib.svg?style=svg)](https://circleci.com/gh/open-telemetry/opentelemetry-go-contrib)
+[![Docs](https://godoc.org/go.opentelemetry.io/contrib?status.svg)](https://pkg.go.dev/go.opentelemetry.io/contrib)
+[![Go Report Card](https://goreportcard.com/badge/go.opentelemetry.io/contrib)](https://goreportcard.com/report/go.opentelemetry.io/contrib)
+[![Gitter](https://badges.gitter.im/open-telemetry/opentelemetry-go.svg)](https://gitter.im/open-telemetry/opentelemetry-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
+Collection of 3rd-party instrumentation and exporters for [OpenTelemetry-Go](https://github.com/open-telemetry/opentelemetry-go).
 
+## Contents
+
+- [Instrumentation](./instrumentation/): Packages providing OpenTelemetry instrumentation for 3rd-party libraries.
+- [Exporters](./exporters/): Packages providing OpenTelemetry exporters for 3rd-party telemetry systems.
+
+## Contributing
+
+For information on how to contribute, consult [the contributing guidelines](./CONTRIBUTING.md)

instrumentation/README.md

@@ -0,0 +1,37 @@
+# Instrumentation
+
+Code contained in this directory contains instrumentation for 3rd-party Go packages.
+
+## Organization
+
+In order to ensure the maintainability and discoverability of instrumentation packages, the following guidelines MUST be followed.
+
+### Packaging
+
+All instrumentation packages MUST be of the form:
+
+```
+go.opentelemetry.io/contrib/instrumentation/{PACKAGE}
+```
+
+Where `{PACKAGE}` is the name of the package being instrumented.
+
+For example:
+
+- `go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux`
+- `go.opentelemetry.io/contrib/instrumentation/gopkg.in/macaron.v1`
+- `go.opentelemetry.io/contrib/instrumentation/database/sql`
+
+Consequentially, this means that all instrumentation MUST be contained in a sub-directory structure matching the package name.
+
+### Contents
+
+All instrumentation packages MUST adhere to [the projects' contributing guidelines](../CONTRIBUTING.md).
+Additionally the following guidelines for package composition need to be followed.
+
+- All instrumentation packages MUST be a Go package.
+   Therefore, an appropriately configured `go.mod` and `go.sum` need to exist for each package.
+- To help understand the instrumentation a Go package documentation SHOULD be included.
+   This documentation SHOULD be in a dedicated `doc.go` file if the package is more than one file.
+   It SHOULD contain useful information like what the purpose of the instrumentation is, how to use it, and any compatibility restrictions that might exist. 
+- Examples of how to actually use the instrumentation SHOULD be included.

instrumentation/macaron/go.mod → instrumentation/gopkg.in/macaron.v1/go.mod

@@ -2,11 +2,11 @@ module go.opentelemetry.io/contrib/instrumentation/macaron
 
 go 1.14
 
+replace go.opentelemetry.io/contrib => ../../..
+
 require (
 	github.com/stretchr/testify v1.5.1
 	go.opentelemetry.io/contrib v0.6.1
 	go.opentelemetry.io/otel v0.6.0
 	gopkg.in/macaron.v1 v1.3.5
 )
-
-replace go.opentelemetry.io/contrib => ../../