diff --git a/README.md b/README.md
index f6fda0bb..73d26844 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ OpenPGP.js
 
 For server side use, install via npm:
 
-    npm install openpgp
+    npm install --save openpgp
 
 
 ### Browser support
@@ -20,7 +20,7 @@ For use in browser, install via bower:
 
 Or Fetch a minified build under [dist](https://github.com/openpgpjs/openpgpjs/tree/master/dist).
 
-The library can be loaded via  AMD/require.js or accessed globally via `window.openpgp`.
+The library can be loaded as a common.js module, a AMD/require.js module or accessed globally via `window.openpgp`.
 
 
 ### Dependencies
@@ -32,11 +32,32 @@ OpenPGP.js uses ES6 promises which are available in [most modern browsers](http:
 
 ### Examples
 
+#### Generate new keypair
+```js
+var openpgp = require('openpgp');
+
+var options = {
+    numBits: 2048,
+    userId: 'Jon Smith <jon.smith@example.org>',
+    passphrase: 'super long and hard to guess secret'
+};
+
+openpgp.generateKeyPair(options).then(function(keypair) {
+    // success
+    var privkey = keypair.privateKeyArmored;
+    var pubkey = keypair.publicKeyArmored;
+}).catch(function(error) {
+    // failure
+});
+```
+
 #### Encryption
 ```js
 var openpgp = require('openpgp');
+
 var key = '-----BEGIN PGP PUBLIC KEY BLOCK ... END PGP PUBLIC KEY BLOCK-----';
 var publicKey = openpgp.key.readArmored(key);
+
 openpgp.encryptMessage(publicKey.keys, 'Hello, World!').then(function(pgpMessage) {
     // success
 }).catch(function(error) {
@@ -47,11 +68,14 @@ openpgp.encryptMessage(publicKey.keys, 'Hello, World!').then(function(pgpMessage
 #### Decryption
 ```js
 var openpgp = require('openpgp');
+
 var key = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK-----';
 var privateKey = openpgp.key.readArmored(key).keys[0];
 privateKey.decrypt('passphrase');
+
 var pgpMessage = '-----BEGIN PGP MESSAGE ... END PGP MESSAGE-----';
 pgpMessage = openpgp.message.readArmored(pgpMessage);
+
 openpgp.decryptMessage(privateKey, pgpMessage).then(function(plaintext) {
     // success
 }).catch(function(error) {
@@ -59,6 +83,10 @@ openpgp.decryptMessage(privateKey, pgpMessage).then(function(plaintext) {
 });
 ```
 
+### Documentation
+
+A jsdoc build of our code comments is available at [doc/index.html](http://openpgpjs.org/openpgpjs/doc/index.html). Public calls should generally be made through the OpenPGP object [doc/openpgp.html](http://openpgpjs.org/openpgpjs/doc/module-openpgp.html).
+
 ### Security recommendations
 
 It should be noted that js crypto apps deployed via regular web hosting (a.k.a. [**host-based security**](https://www.schneier.com/blog/archives/2012/08/cryptocat.html)) provide users with less security than installable apps with auditable static versions. Installable apps can be deployed as a [Firefox](https://developer.mozilla.org/en-US/Marketplace/Publishing/Packaged_apps) or [Chrome](http://developer.chrome.com/apps/about_apps.html) packaged app. These apps are basically signed zip files and their runtimes typically enforce a strict [Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/) to protect users against [XSS](http://en.wikipedia.org/wiki/Cross-site_scripting). This [blogpost](http://tonyarcieri.com/whats-wrong-with-webcrypto) explains the trust model of the web quite well.
@@ -71,10 +99,6 @@ To create your own build of the library, just run the following command after cl
 
     npm install && npm test
 
-### Documentation
-
-A jsdoc build of our code comments is available at [doc/index.html](http://openpgpjs.org/openpgpjs/doc/index.html). Public calls should generally be made through the OpenPGP object [doc/openpgp.html](http://openpgpjs.org/openpgpjs/doc/module-openpgp.html).
-
 ### Mailing List
 
 You can [sign up](http://list.openpgpjs.org/) for our mailing list and ask for help there.  We've recently worked on getting our [archive up and running](http://www.mail-archive.com/list@openpgpjs.org/).