Improved some of the wording of the docs.

docs/client.rst

@@ -41,16 +41,11 @@ Example implementation:
 Dealing with Reports
 ====================
 
-Receiving reports
------------------
-
-Upon registration, the server will tell you which reports it has available.
-
-
+The VTN Server will most like want to receive some reports like metering values or availability status from you.
 Providing reports
 -----------------
 
-If you tell pyOpenADR what reports you are able to provide, and give it a handler that will retrieve those reports from your own systems, pyOpenADR will make sure that the server receives the reports it asks for and at the requested interval.
+If you tell OpenLEADR what reports you are able to provide, and give it a handler that will retrieve those reports from your own systems, OpenLEADR will make sure that the server receives the reports it asks for and at the requested interval.
 
 For example: you can provide 15-minute meter readings for an energy meter at your site. You have a coroutine set up like this:
 
@@ -85,7 +80,8 @@ If you want you client to automatically sign your outgoing messages, use the fol
 .. code-block:: python3
 
     async def main():
-        client = OpenADRClient(ven_name='MyVEN', vtn_url='https://localhost:8080/',
+        client = OpenADRClient(ven_name='MyVEN',
+                               vtn_url='https://localhost:8080/',
                                cert='/path/to/cert.pem',
                                key='/path/to/key.pem',
                                passphrase='my-key-password')
@@ -101,7 +97,10 @@ You can validate incoming messages against a public key.
 .. code-block:: python3
 
     async def main():
-        client = OpenADRClient(ven_name='MyVEN', vtn_url='https://localhost:8080/',
-                               verification_cert='/path/to/cert.pem')
+        client = OpenADRClient(ven_name='MyVEN',
+                               vtn_url='https://localhost:8080/',
+                               vtn_fingerprint='AA:BB:CC:DD:EE:FF:11:22:33:44')
 
 This will automatically validate check that incoming messages are signed by the private key that belongs to the provided (public) certificate. If validation fails, you will see a Warning emitted, but the message will not be delivered to your handlers, protecting you from malicious messages being processed by your system. The sending party will see an error message returned.
+
+You should use both of the previous examples combined to secure both the incoming and the outgoing messages.

docs/features.rst

@@ -7,25 +7,31 @@ Feature Tour
 Automatic registration
 ----------------------
 
+Registering your VEN to a VTN is a process that requires some service discovery, exchange of reporting capabilitiets, assignment of a VEN_ID, et cetera. You don't have to see any of this in your own code. Just create a new OpenADRClient instance, provide a VTN URL, a VEN name, optionally provide signing certificates and a verification fingerprint, and registration happens automatically.
 
 
 Automatic reporting
 -------------------
 
+If you're implementing a VEN (client), you configure which types of reports you can offer, you provide handlers that retrieve the measurements, and OpenLEADR will take care of the rest. It will offer the reports to the VTN, allow the VTN to pick the reports it requires, and it will call your data collection handlers at a set interval, and pack up the values into the reports.
+
+If you're implementing a VTN (server), you configure which types of reports you wish to receive, and it will automatically request these reports from the VEN. Whenever new data arrives, it will call one of your handlers so you can hand the data off to your own systems for processing and archiving.
 
 
 Event-driven
 ------------
 
+Once you have configured your client or server, all routine interactions happen automatically: polling for new Events, requesting reports, et cetera. Whenever OpenLEADR needs some information or data that it does not have, it will call your handlers in order to get it. Your handlers only have to deal with a very specific set of cases and they can usually be quite simple.
 
 
-Dict-representations
---------------------
+Dict-style representations
+--------------------------
 
+Although OpenADR is an XML-based protocol that is either transported over HTTP or XMPP, you don't need to see any XML or custom object types at all. You use native Python dicts (and native Python types like `datetime.datetime` and `datetime.timedelta`) in your handlers.
 
 
 Message Signing for secure communications
 -----------------------------------------
 
-If you provide a PEM-formatted certificate and key, all outgoing messages will be cryptographically signed. In addition, both the client and server can supply a public PEM-formatted certificate to verify all incoming messages, to make sure they came from a trusted source.
+If you provide a PEM-formatted certificate and key, all outgoing messages will be cryptographically signed. If you also provide a fingerprint for the other side's certificate, incoming messages can be securely authenticated and verified.
 

docs/index.rst

@@ -14,8 +14,7 @@ Key Features
 
 - Fully compliant OpenADR 2.0b implementation for both servers (Virtual Top Node) and clients (Virtual End Node)
 - Fully asyncio: you set up the coroutines that can handle certain events, and they get called when needed.
-- All messages are represented as simple Python dictionaries. All XML parsing and generation is done for you.
-- You only have to deal with your own logic.
+- Fully pythonic: all messages are represented as simple Python dictionaries. All XML parsing and generation is done for you.
 
 Take a :ref:`feature_tour`!