diff --git a/db.go b/db.go
index 54de22c..74f3410 100644
--- a/db.go
+++ b/db.go
@@ -1,4 +1,3 @@
-// Package dynamo offers a rich DynamoDB client.
 package dynamo
 
 import (
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..c368c53
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,84 @@
+// Package dynamo offers a rich DynamoDB client.
+/*
+
+dynamo is an expressive client for Go, with an API heavily inspired by mgo. dynamo integrates with the official AWS SDK.
+
+dynamo is still under development, so the API may change rarely. However, breaking changes will be avoided and the API can be considered relatively stable.
+
+*/
+//
+// Simple Example
+//
+// This is a simple complete example that you can run
+/*
+	package dynamo
+
+	import (
+		"time"
+
+		"github.com/aws/aws-sdk-go/aws"
+		"github.com/aws/aws-sdk-go/aws/session"
+		"github.com/guregu/dynamo"
+	)
+
+	// Use struct tags much like the standard JSON library,
+	// you can embed anonymous structs too!
+	type widget struct {
+		UserID int       // Hash key, a.k.a. partition key
+		Time   time.Time // Range key, a.k.a. sort key
+
+		Msg       string              `dynamo:"Message"`
+		Count     int                 `dynamo:",omitempty"`
+		Friends   []string            `dynamo:",set"` // Sets
+		Set       map[string]struct{} `dynamo:",set"` // Map sets, too!
+		SecretKey string              `dynamo:"-"`    // Ignored
+		Category  string              `dynamo:"Category"` // Global Secondary Index
+		Children  []any               // Lists
+	}
+
+
+	func main() {
+		db := dynamo.New(session.New(), &aws.Config{Region: aws.String("us-west-2")})
+		table := db.Table("Widgets")
+
+		// put item
+		w := widget{UserID: 613, Time: time.Now(), Msg: "hello"}
+		err := table.Put(w).Run()
+
+		// update item field
+		w.Msg = "hello again"
+		m, err := dynamo.MarshalItem(w)
+		err = table.Update("UserID", m["UserID"]).
+			Set("Msg", m["Msg"]).
+			Run()
+
+		// get the same item
+		var result widget
+		err = table.Get("UserID", w.UserID).
+			Range("Time", dynamo.Equal, w.Time).
+			Filter("'Count' = ? AND $ = ?", w.Count, "Message", w.Msg). // placeholders in expressions
+			One(&result)
+
+		// get by index
+		err = table.Get("Category", "hoge").
+			Index("category-index").
+			One(&result)
+
+		// get all items
+		var results []widget
+		err = table.Scan().All(&results)
+	}
+*/
+//
+// Struct Tags Example
+//
+// This example shows the usage of tags to define the keys and rename fields
+// Use `hash` for the hash key, and `range` or `sort` for the range/sort key
+/*
+	type yourType struct {
+		ID   string `dynamo:"pk,hash"`
+		Timestamp   string `dynamo:"sk,hash"`
+		Data string `dynamo:"data"`
+	}
+*/
+package dynamo
diff --git a/doc_test.go b/doc_test.go
new file mode 100644
index 0000000..413c537
--- /dev/null
+++ b/doc_test.go
@@ -0,0 +1,82 @@
+package dynamo_test
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/aws/aws-sdk-go/aws"
+	"github.com/aws/aws-sdk-go/aws/session"
+	"github.com/guregu/dynamo"
+)
+
+// yourType is a helper type to be used in the examples below
+type yourType struct {
+	PK   string `dynamo:"pk,hash"`
+	SK   string `dynamo:"sk,hash"`
+	Data string `dynamo:"data"`
+}
+
+// Table Put example shows how to insert (or replace) a new Item
+func ExampleTable_Put() {
+	// db table setup
+	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("region")})
+	dynaTable := db.Table("table")
+
+	dynaTable.Put(yourType{PK: "key", SK: "range key", Data: "your data"}).Run()
+}
+
+// Table Update example on soft deleting an Item.
+// Other examples show how to ignore these soft-deleted Items
+func ExampleTable_Update_softdelete() {
+	// db table setup
+	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("region")})
+	dynaTable := db.Table("table")
+
+	dynaTable.Update("pk", "word").Range("sk", "range_key").AddStringsToSet("deleted_at", time.Now().Format(time.RFC3339)).Run()
+}
+
+// Table Update on conditional updating
+// This will only add 1 to attribute "count" if "count" = 0 or it does not exists
+func ExampleTable_Update_conditional() {
+	// db table setup
+	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("region")})
+	dynaTable := db.Table("table")
+
+	dynaTable.Update("pk", "word").Range("sk", "range key").Add("count", 1).If("'count' = ? OR attribute_not_exists('count')", 0).Run()
+}
+
+// Table Scan with filter show how to do a table scan taing a sort key into account, and ignoring soft_deleted items
+func ExampleTable_Scan_scanfiltered() {
+	// db table setup
+	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("region")})
+	dynaTable := db.Table("table")
+
+	var values []yourType
+	dynaTable.Scan().Filter("sk = ? AND attribute_not_exists('deleted_at')", "range key value").All(&values)
+	fmt.Println(values)
+}
+
+// Table Batch shows how to iterate over several items with different keys
+// In this example, the range key is considered the same, but it could be different as well
+func ExampleTable_Batch_getkeys() {
+	// db table setup
+	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("region")})
+	dynaTable := db.Table("table")
+
+	// prepare the request with they key pairs
+	var wordKeys []dynamo.Keyed
+	words := []string{"a", "b", "c"}
+	for word := range words {
+		wordKeys = append(wordKeys, dynamo.Keys{word, "range key"})
+	}
+
+	// here "pk", "sk" are the names of the hash and range key fields in the DynamoDB table
+	iterator := dynaTable.Batch("pk", "sk").Get(wordKeys...).Iter()
+	var value yourType
+	for iterator.Next(&value) {
+		fmt.Println(value)
+	}
+	if err := iterator.Err(); err != nil {
+		fmt.Println(err)
+	}
+}