diff --git a/doc.go b/doc.go
index 4879f7a4..e41d635d 100644
--- a/doc.go
+++ b/doc.go
@@ -1 +1,9 @@
+// Package app provides experimental utilities to make Compose files more
+// reusable and sharable.
+//
+// The `cmd/docker-app` package generates the `docker-app` binary,
+// see https://github.com/docker/app for more information about it.
+//
+// It can also be used as a library to be integrated in your tools.
+// Usage examples are provided inline with their full documentation.
 package app
diff --git a/examples_test.go b/examples_test.go
new file mode 100644
index 00000000..a42b62f9
--- /dev/null
+++ b/examples_test.go
@@ -0,0 +1,48 @@
+package app
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/docker/app/loader"
+	"github.com/docker/app/render"
+	yaml "gopkg.in/yaml.v2"
+)
+
+func Example() {
+	// Load the file (single-file format, there is multiple format)
+	f, err := os.Open("./examples/hello-world/hello-world.dockerapp")
+	if err != nil {
+		panic("cannot read application")
+	}
+	defer f.Close()
+	app, err := loader.LoadFromSingleFile("myApp", f)
+	if err != nil {
+		panic("cannot load application")
+	}
+	// Render the app to a composefile format, using some user provided settings
+	c, err := render.Render(app, map[string]string{
+		"text": "hello examples!",
+	})
+	if err != nil {
+		panic("cannot render application")
+	}
+	// Marshal it to yaml (to display it)
+	s, err := yaml.Marshal(c)
+	if err != nil {
+		panic("cannot marshall the composefile in yaml")
+	}
+	fmt.Print(string(s))
+	// Output: version: "3.6"
+	// services:
+	//   hello:
+	//     command:
+	//     - -text
+	//     - hello examples!
+	//     image: hashicorp/http-echo
+	//     ports:
+	//     - mode: ingress
+	//       target: 5678
+	//       published: 8080
+	//       protocol: tcp
+}