diff --git a/README.md b/README.md
index 05cfedf1..9e35a0f5 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,29 @@
 
 # pgconn
 
-Package pgconn is a low-level PostgreSQL database driver.
+Package pgconn is a low-level PostgreSQL database driver. It operates at nearly the same level is the C library libpq.
+It is primarily intended to serve as the foundation for higher level libraries such as https://github.com/jackc/pgx.
+Applications should handle normal queries with a higher level library and only use pgconn directly when required for
+low-level access to PostgreSQL functionality.
 
-It is intended to serve as the foundation for the next generation of https://github.com/jackc/pgx.
+## Example Usage
+
+```go
+pgConn, err := pgconn.Connect(context.Background(), os.Getenv("DATABASE_URL"))
+if err != nil {
+	log.Fatalln("pgconn failed to connect:", err)
+}
+defer pgConn.Close()
+
+result := pgConn.ExecParams(context.Background(), "select email from users where id=$1", [][]byte{[]byte("123")}, nil, nil, nil)
+for result.NextRow() {
+	fmt.Println("User 123 has email:", string(result.Values()[0]))
+}
+_, err := result.Close()
+if err != nil {
+	log.Fatalln("failed reading result:", err)
+})
+```
 
 ## Testing
 
diff --git a/config.go b/config.go
index c751cc0d..98755b1f 100644
--- a/config.go
+++ b/config.go
@@ -121,6 +121,13 @@ func NetworkAddress(host string, port uint16) (network, address string) {
 // security guarantees than it would with libpq. Do not rely on this behavior as it
 // may be possible to match libpq in the future. If you need full security use
 // "verify-full".
+//
+// Other known differences with libpq:
+//
+// If a host name resolves into multiple addresses, libpq will try all addresses. pgconn will only try the first.
+//
+// When multiple hosts are specified, libpq allows them to have different passwords set via the .pgpass file. pgconn
+// does not.
 func ParseConfig(connString string) (*Config, error) {
 	settings := defaultSettings()
 	addEnvSettings(settings)
diff --git a/pgconn.go b/pgconn.go
index 9e4f6253..3deb8563 100644
--- a/pgconn.go
+++ b/pgconn.go
@@ -390,7 +390,7 @@ func (pgConn *PgConn) hardClose() error {
 	return pgConn.conn.Close()
 }
 
-// TODO - rethink how to report status. At the moment this is just a temporary measure so pgx.Conn can detect deatch of
+// TODO - rethink how to report status. At the moment this is just a temporary measure so pgx.Conn can detect death of
 // underlying connection.
 func (pgConn *PgConn) IsAlive() bool {
 	return pgConn.status >= connStatusIdle