diff --git a/lang/js/README b/lang/js/README
index b7cd3d72..fd95cc45 100644
--- a/lang/js/README
+++ b/lang/js/README
@@ -1,16 +1,41 @@
-gpgme.js, as contained in this directory, is a javascript library for direct use
-of gnupg in browsers, with the help of nativeMessaging.
+gpgme.js - JavaScript for GPGME
+-------------------------------
+Initially developed for integration with the Mailvelope Web Extension.
+
+Overview
+--------
+
+gpgme.js is a javascript library for direct use of GnuPG in browsers.
+It interacts with GPGME through nativeMessaging and gpgme-json.
+
+It is meant to be distributed directly by its downstream users in
+their extension package. As such it is not integrated in the
+autotools build system. See build instructions below.
+
+
+gpgme-json
+----------
+
+gpgme-json (see core src/gpgme-json.c) the json to GPGME bridge is
+required as native messaging backend for gpgme.js to work.
+It needs to be installed and registered as native messaging
+backend with the browser.
+
+See gpgme-mozilla.json and gpgme-chrome.json examples in
+the top level doc/examples as example manifests.
+
+Any web extension using gpgme.js will need to be whitelisted in the manifest
+file by its id.
+
+Distributors are encouraged to create manifest packages for their
+distributions.
 
-Prerequisites:
---------------
-gpgme.js will make use of the application gpgme-json, which is distributed with
-gpgme. Gpgme-json needs to be installed; it will further need to accept the
-browser extension in the manifest file.
 
 Building gpgme.js
 -----------------
-gpgme.js uses webpack, and thus depends on nodejs for building. All
-dependencies will be installed (in a local subdirectory) with the command
+
+gpgme.js uses webpack, and thus depends on Node.js for building.
+All dependencies will be installed (in a local subdirectory) with the command
 `npm install`.
 
 To create a current version of the package, the command is
@@ -18,6 +43,7 @@ To create a current version of the package, the command is
 If you want a more debuggable (i.e. not minified) build, just change the mode
 in webpack.conf.js.
 
+
 Demo and Test WebExtension:
 ---------------------------
 
@@ -82,6 +108,7 @@ is needed, with the following content:
   The manifest for linux is usually placed at:
     `~/.mozilla/native-messaging-hosts/gpgmejson.json`
 
+
 Documentation
 -------------