diff --git a/README.md b/README.md
index fa892a8..ce579b3 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,79 @@
-See docs https://godoc.org/github.com/micromdm/mdm
+[](http://godoc.org/github.com/micromdm/mdm) [](https://travis-ci.org/micromdm/mdm)
+
+The mdm package holds structs and helper methods for payloads in Apple's Mobile Device Management protocol.
+This package embeds the various payloads and responses in two structs - `Payload` and `Response`.
+
+# How an MDM server executes commands on a device.
+To communicate with a device, an MDM server must create a Payload property list with a specific RequestType and additional data for each request type. Let's use the DeviceInformation request as an example:
+
+
+```
+ // create a request
+ request := &CommandRequest{
+ RequestType: "DeviceInformation",
+ Queries: []string{"IsCloudBackupEnabled", "BatteryLevel"},
+ }
+
+ // NewPayload will create a proper Payload based on the CommandRequest struct
+ payload, err := NewPayload(request)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Encode in a plist and print to stdout
+ // uses the github.com/groob/plist package
+ encoder := plist.NewEncoder(os.Stdout)
+ encoder.Indent(" ")
+ if err := encoder.Encode(payload); err != nil {
+ log.Fatal(err)
+ }
+```
+
+Resulting command payload:
+```
+
+
+
+
+ Command
+
+ Queries
+
+ IsCloudBackupEnabled
+ BatteryLevel
+
+ RequestType
+ DeviceInformation
+
+ CommandUUID
+ fa34b4b7-0553-4b3a-9c4b-76b8b357a622
+
+
+```
+
+An MDM server will queue this request and send a push notification to a device. When device checks in, the server will
+reply with the queued plist.
+
+Once the device receives and processes the payload plist, it will reply back to the server. The response will be another plist, which can be unmarshalled into the `Response` struct. Below is the response to our DeviceInformation request.
+
+```
+
+
+
+
+ CommandUUID
+ fa34b4b7-0553-4b3a-9c4b-76b8b357a622
+ QueryResponses
+
+ BatteryLevel
+ 1
+ IsCloudBackupEnabled
+
+
+ Status
+ Acknowledged
+ UDID
+ 1111111111111111111111111111111111111111
+
+
+```