diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml
index 5f61b01..153eeac 100644
--- a/.github/workflows/integration.yml
+++ b/.github/workflows/integration.yml
@@ -7,10 +7,10 @@ jobs:
     name: Integration tests
     runs-on: ubuntu-latest
     steps:
-    - name: Set up Go 1.13
+    - name: Set up Go 1.15
       uses: actions/setup-go@v2
       with:
-        go-version: 1.13
+        go-version: 1.15
       id: go
 
     - name: Install Protoc
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 9b6402a..c687a35 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -24,7 +24,7 @@ jobs:
       - name: Set up Go 1.13
         uses: actions/setup-go@v1
         with:
-          go-version: 1.13
+          go-version: 1.15
         id: go
 
       - name: Check out code into the Go module directory
diff --git a/answer/proto/answer.proto b/answer/proto/answer.proto
index e0418e3..00651d0 100644
--- a/answer/proto/answer.proto
+++ b/answer/proto/answer.proto
@@ -8,7 +8,7 @@ service Answer {
 	rpc Question(QuestionRequest) returns (QuestionResponse) {}
 }
 
-// Answer a question and receive an instant answer
+// Ask a question and receive an instant answer
 message QuestionRequest {
 	// the question to answer
 	string query = 1;
diff --git a/cache/README.md b/cache/README.md
index f8b1e53..4ef2033 100644
--- a/cache/README.md
+++ b/cache/README.md
@@ -2,6 +2,6 @@ Quick access key-value storage
 
 # Cache Service
 
-The cache service provides simple get/set/delete key-value storage along with ttl support.
+The cache service provides simple get/set/delete key-value storage. Values can be stored with an optional time-to-live (TTL) to automatically expire entries.
 
-The max value size is 1mb
+The max value size is 1MB.
diff --git a/cache/proto/cache.proto b/cache/proto/cache.proto
index 157c42b..8dd5a96 100644
--- a/cache/proto/cache.proto
+++ b/cache/proto/cache.proto
@@ -53,32 +53,32 @@ message DeleteResponse {
 	string status = 1;
 }
 
-// Increment a value (if its a number)
+// Increment a value (if it's a number)
 message IncrementRequest {
 	// The key to increment
 	string key = 1;
-	// The value to add
+	// The amount to increment the value by
 	int64 value = 2;
 }
 
 message IncrementResponse {
 	// The key incremented
 	string key = 1;
-	// The result value
+	// The new value
 	int64 value = 2;
 }
 
-// Decrement a value (if its a number)
+// Decrement a value (if it's a number)
 message DecrementRequest {
 	// The key to decrement
 	string key = 1;
-	// The delta value to decrement
+	// The amount to decrement the value by
 	int64 value = 2;
 }
 
 message DecrementResponse {
-	// The key of the item
+	// The key decremented
 	string key = 1;
-	// The result value of the item
+	// The new value
 	int64 value = 2;
 }
diff --git a/crypto/README.md b/crypto/README.md
index 226a141..a72ae34 100644
--- a/crypto/README.md
+++ b/crypto/README.md
@@ -1,7 +1,7 @@
-Cryptocurrency prices, quotes and news
+Cryptocurrency prices, quotes, and news
 
 # Crypto Service
 
-Get up to the second cryptocurrency prices, quotes, previous close information and news.
+Get up to the second cryptocurrency prices, quotes, previous close information, and news.
 
 Powered by [Finage](https://finage.co.uk)
diff --git a/crypto/proto/crypto.proto b/crypto/proto/crypto.proto
index 05cfdca..9c7a98a 100644
--- a/crypto/proto/crypto.proto
+++ b/crypto/proto/crypto.proto
@@ -39,7 +39,7 @@ message NewsResponse {
 
 // Get the last price for a given crypto ticker
 message PriceRequest {
-	// crypto symbol e.g BTCUSD
+	// the crypto symbol e.g BTCUSD
 	string symbol = 1;
 }
 
@@ -50,7 +50,7 @@ message PriceResponse {
 	double price = 2;
 }
 
-// Get the last quote for the crypto
+// Get the last quote for a given crypto ticker
 message QuoteRequest {
 	// the crypto symbol e.g BTCUSD
 	string symbol = 1;
diff --git a/db/README.md b/db/README.md
index 6ff8408..de82474 100644
--- a/db/README.md
+++ b/db/README.md
@@ -2,4 +2,4 @@ Simple database service
 
 # DB Service
 
-The DB service is a simple database which provides persistent storage via a CRUD API. It includes fast querying, ordering and more.
+The DB service is a simple database which provides persistent storage via a Create Read Update Delete (CRUD) API. It includes fast querying, ordering, and more.
diff --git a/db/proto/db.proto b/db/proto/db.proto
index 40bd006..06d7b62 100644
--- a/db/proto/db.proto
+++ b/db/proto/db.proto
@@ -16,7 +16,7 @@ service Db {
 
 // Read data from a table. Lookup can be by ID or via querying any field in the record.
 message ReadRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// Read by id. Equivalent to 'id == "your-id"'
 	string id = 2;
@@ -27,7 +27,7 @@ message ReadRequest {
 	// Accessing list elements is not supported yet.
 	string query = 3;
 	int32 offset = 4;
-	// Default limit is 25.
+	// Maximum number of records to return. Default limit is 25.
 	// Maximum limit is 1000. Anything higher will return an error.
 	int32 limit = 5;
 	// field name to order by
@@ -41,9 +41,9 @@ message ReadResponse {
 	repeated google.protobuf.Struct records = 1;
 }
 
-// Create a record in the database. Optionally include an "id" field otherwise its set automatically.
+// Create a record in the database. Optionally include an "id" field otherwise it's set automatically.
 message CreateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// JSON encoded record or records (can be array or object)
 	google.protobuf.Struct record = 2;
@@ -56,9 +56,9 @@ message CreateResponse {
 
 // Update a record in the database. Include an "id" in the record to update.
 message UpdateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
-	// The id of the record
+	// The id of the record. If not specified it is inferred from the 'id' field of the record
 	string id = 2;
 	// record, JSON object
 	google.protobuf.Struct record = 3;
@@ -68,7 +68,7 @@ message UpdateResponse {}
 
 // Delete a record in the database by id.
 message DeleteRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// id of the record
 	string id = 2;
@@ -80,7 +80,7 @@ message DeleteResponse {
 
 // Truncate the records in a table
 message TruncateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 }
 
diff --git a/email/README.md b/email/README.md
index 8351b5e..7b7859a 100644
--- a/email/README.md
+++ b/email/README.md
@@ -2,7 +2,7 @@ Send emails in a flash
 
 # Emails Service
 
-A quick and easy email api. Simply provide a from, to and text or html body.
+A quick and easy email API. Simply provide a from, to, and text or html body.
 
 Powered by [Sendgrid](https://sendgrid.com)
 
diff --git a/email/proto/email.proto b/email/proto/email.proto
index ff34326..06fd5a3 100644
--- a/email/proto/email.proto
+++ b/email/proto/email.proto
@@ -8,9 +8,9 @@ service Email {
 	rpc Send(SendRequest) returns (SendResponse) {}
 }
 
-// Send an email by passing in from, to, subject and a text or html body
+// Send an email by passing in from, to, subject, and a text or html body
 message SendRequest {
-	// the name of the sender
+	// the display name of the sender
 	string from = 1;
 	// the email address of the recipient
 	string to = 2;
diff --git a/emoji/proto/emoji.proto b/emoji/proto/emoji.proto
index 7292834..c3d9e4d 100644
--- a/emoji/proto/emoji.proto
+++ b/emoji/proto/emoji.proto
@@ -45,9 +45,9 @@ message PrintResponse {
 	string text = 1;
 }
 
-// Send an emoji to anyone via SMS
+// Send an emoji to anyone via SMS. Messages are sent in the form '<message> Sent from <from>'
 message SendRequest {
-	// who the message is from e.g Alice
+	// the name of the sender from e.g Alice
 	string from = 1;
 	// phone number to send to (including international dialing code)
 	string to = 2;
diff --git a/file/README.md b/file/README.md
index b8108f8..c431d11 100644
--- a/file/README.md
+++ b/file/README.md
@@ -1,5 +1,5 @@
-Store, list and retrieve text files
+Store, list, and retrieve text files
 
 # File Service
 
-Save, list and retrieve text files by project and path.
+Save, list, and retrieve text files. Files can have a path in the same way they would on your computer e.g.`/documents/text-files/file.txt`. Files can optionally be grouped in to projects.
diff --git a/file/proto/file.proto b/file/proto/file.proto
index b44b37a..4b2d0eb 100644
--- a/file/proto/file.proto
+++ b/file/proto/file.proto
@@ -56,12 +56,12 @@ message SaveRequest {
 message SaveResponse {
 }
 
-// List file by their project and optionally a path.
+// List files by their project and optionally a path.
 message ListRequest {
 	// Project, required for listing.
 	string project = 1;
 	// Defaults to '/', ie. lists all files in a project.
-	// Supply path if of a folder if you want to list
+	// Supply path to a folder if you want to list
 	// files inside that folder
 	// eg. '/docs'
 	string path = 2;
diff --git a/forex/README.md b/forex/README.md
index 224205b..2589a19 100644
--- a/forex/README.md
+++ b/forex/README.md
@@ -1,8 +1,8 @@
-Foreign Exchange (FX) rates
+Foreign exchange (FX) rates
 
 # Forex Service
 
-Real-time and Historical Foreign Exchange (FX) rates from over 200 world currencies. 
+Real-time and historical foreign exchange (FX) rates for over 200 world currencies. Get the latest rates and bid/ask prices. 
 
 Powered by [Finage](https://finage.co.uk)
 
diff --git a/forex/proto/forex.proto b/forex/proto/forex.proto
index 091c4b1..677c808 100644
--- a/forex/proto/forex.proto
+++ b/forex/proto/forex.proto
@@ -10,7 +10,7 @@ service Forex {
 	rpc History(HistoryRequest) returns (HistoryResponse) {}
 }
 
-// Get the last price for a given forex ticker
+// Get the latest price for a given forex ticker
 message PriceRequest {
 	// forex symbol e.g GBPUSD
 	string symbol = 1;
@@ -23,7 +23,7 @@ message PriceResponse {
 	double price = 2;
 }
 
-// Get the last quote for the forex
+// Get the latest quote for the forex
 message QuoteRequest {
 	// the forex symbol e.g GBPUSD
 	string symbol = 1;
diff --git a/geocoding/README.md b/geocoding/README.md
index 7a7d33d..0c6caa7 100644
--- a/geocoding/README.md
+++ b/geocoding/README.md
@@ -2,5 +2,5 @@ Geocode an address to gps location and the reverse.
 
 # Geocoding Service
 
-The geocoding service provides address to lat lng geocoding as well as the reverse. 
+The geocoding service provides address to latitude longitude geocoding as well as the reverse. 
 It's useful for building mapping or location based services.
diff --git a/geocoding/proto/geocoding.proto b/geocoding/proto/geocoding.proto
index a66aa44..64bedaf 100644
--- a/geocoding/proto/geocoding.proto
+++ b/geocoding/proto/geocoding.proto
@@ -23,7 +23,7 @@ message Location {
 	double longitude = 2;
 }
 
-// Lookup returns a geocoded address including normalized address and gps coordinates
+// Lookup returns a geocoded address including normalized address and gps coordinates. All fields are optional, provide more to get more accurate results
 message LookupRequest {
 	string address = 1;
 	string city = 2;
diff --git a/go.mod b/go.mod
index 28cff8e..8a328e0 100644
--- a/go.mod
+++ b/go.mod
@@ -1,16 +1,14 @@
 module github.com/micro/services
 
-go 1.14
+go 1.15
 
 require (
-	github.com/HdrHistogram/hdrhistogram-go v1.1.0 // indirect
 	github.com/Masterminds/semver/v3 v3.1.1
 	github.com/PuerkitoBio/goquery v1.6.1
 	github.com/SlyMarbo/rss v1.0.1
 	github.com/asim/mq v0.1.0
 	github.com/cdipaolo/goml v0.0.0-20190412180403-e1f51f713598 // indirect
 	github.com/cdipaolo/sentiment v0.0.0-20200617002423-c697f64e7f10
-	github.com/cpuguy83/go-md2man/v2 v2.0.0 // indirect
 	github.com/crufter/lexer v0.0.0-20120907053443-23fe8c7add01
 	github.com/disintegration/imaging v1.6.2
 	github.com/enescakir/emoji v1.0.0
@@ -32,8 +30,6 @@ require (
 	github.com/mattheath/kala v0.0.0-20171219141654-d6276794bf0e
 	github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3
 	github.com/miekg/dns v1.1.31 // indirect
-	github.com/onsi/ginkgo v1.15.0 // indirect
-	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/oschwald/geoip2-golang v1.5.0
 	github.com/patrickmn/go-cache v2.1.0+incompatible
 	github.com/paulmach/go.geo v0.0.0-20180829195134-22b514266d33
@@ -46,8 +42,6 @@ require (
 	github.com/tkuchiki/go-timezone v0.2.2
 	github.com/ttacon/builder v0.0.0-20170518171403-c099f663e1c2 // indirect
 	github.com/ttacon/libphonenumber v1.2.1 // indirect
-	github.com/uber/jaeger-client-go v2.29.1+incompatible // indirect
-	github.com/uber/jaeger-lib v2.4.1+incompatible // indirect
 	go.opencensus.io v0.22.4 // indirect
 	golang.org/x/crypto v0.0.0-20210322153248-0c34fe9e7dc2
 	golang.org/x/net v0.0.0-20210226172049-e18ecbb05110
diff --git a/go.sum b/go.sum
index ad758d4..e9e1b99 100644
--- a/go.sum
+++ b/go.sum
@@ -358,8 +358,6 @@ github.com/mattn/go-sqlite3 v1.14.5 h1:1IdxlwTNazvbKJQSxoJ5/9ECbEeaTTyeU7sEAZ5KK
 github.com/mattn/go-sqlite3 v1.14.5/go.mod h1:WVKg1VTActs4Qso6iwGbiFih2UIHo0ENGwNd0Lj+XmI=
 github.com/mattn/go-tty v0.0.0-20180219170247-931426f7535a/go.mod h1:XPvLUNfbS4fJH25nqRHfWLMa1ONC8Amw+mIA639KxkE=
 github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
-github.com/micro/micro/v3 v3.3.1-0.20210611161948-fd9821dd4f52 h1:laHYhHMiGtbv/jjykUubxxGW+1HAgTi0RFDsNOnwXxg=
-github.com/micro/micro/v3 v3.3.1-0.20210611161948-fd9821dd4f52/go.mod h1:0NVo+HuGK22cbFqkLe59rGZZeXh2++XBfhU+xheOh8g=
 github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3 h1:oS7027tNGjfpLeLOIFTHF06xXGJ2HjHXfk+8VaU19AY=
 github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3/go.mod h1:cgV1bNfRLOE4vytanTo+N/QvjsdTRJRKTVqKq6XH7AA=
 github.com/miekg/dns v1.1.15/go.mod h1:W1PPwlIAgtquWBMBEV9nkV9Cazfe8ScdGz/Lj7v3Nrg=
diff --git a/helloworld/proto/helloworld.proto b/helloworld/proto/helloworld.proto
index fe706b3..bfa84b4 100644
--- a/helloworld/proto/helloworld.proto
+++ b/helloworld/proto/helloworld.proto
@@ -18,10 +18,11 @@ message Response {
 	string message = 1;
 }
 
-// Stream returns a streaming helloworld response
+// Stream returns a stream of "Hello $name" responses
 message StreamRequest {
 	string name = 1;
-        int64 messages = 2;
+	// the number of messages to send back
+	int64 messages = 2;
 }
 
 message StreamResponse {
diff --git a/id/README.md b/id/README.md
index a235c58..262eb73 100644
--- a/id/README.md
+++ b/id/README.md
@@ -2,5 +2,5 @@ Generate unique IDs (uuid, snowflake, etc)
 
 # ID Service
 
-The ID service provides unique ID generation. Including uuid, snowflake (64 bit) and bigflake (128 bit)
+The ID service provides unique ID generation. Including UUID, [snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) (64 bit) and [bigflake](https://archive.is/2015.07.08-082503/http://www.boundary.com/blog/2012/01/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/) (128 bit)
 
diff --git a/image/README.md b/image/README.md
index ad60812..3a03d66 100644
--- a/image/README.md
+++ b/image/README.md
@@ -1,5 +1,5 @@
-Quickly upload, resize and convert images
+Quickly upload, resize, and convert images
 
 # Image Service
 
-The image service provides upload, resize and image conversion. It provides a cdn for uploaded images and a simple API.
+The image service provides upload, resize, and image conversion. It provides a CDN for uploaded images and a simple API.
diff --git a/ip/README.md b/ip/README.md
index 6834d8c..aef5886 100644
--- a/ip/README.md
+++ b/ip/README.md
@@ -2,4 +2,4 @@ IP to geolocation lookup
 
 # IP Service
 
-The IP service provides IP to geolocation lookup including asn, city, country, timezone and lat/long.
+The IP service provides IP to geolocation lookup including asn, city, country, timezone, and latitude/longitude.
diff --git a/location/README.md b/location/README.md
index 86c97cd..8766570 100644
--- a/location/README.md
+++ b/location/README.md
@@ -2,6 +2,9 @@ Real time GPS location tracking and search
 
 # Location Service
 
-Send, store and search real time gps point data and tracking info using the location API. 
+Send, store, and search real time GPS point data and tracking information using the location API. 
+- Record and retrieve the locations of your entities
+- Perform location based search of them including filters
+
 Build powerful map rendered views with up to the second updated points on the map.
 
diff --git a/location/proto/location.proto b/location/proto/location.proto
index 58357e9..b830024 100644
--- a/location/proto/location.proto
+++ b/location/proto/location.proto
@@ -16,9 +16,9 @@ service Location {
 
 // A point is a GPS coordinate.
 message Point {
-        double latitude = 1;
-        double longitude = 2;
-        int64 timestamp = 3;
+	double latitude = 1;
+	double longitude = 2;
+	int64 timestamp = 3;
 }
 
 message Entity {
@@ -53,7 +53,7 @@ message SearchRequest {
 	double radius = 2;
 	// type of entities to filter
 	string type = 3;
-	// number of entities to return
+	// Maximum number of entities to return
 	int64 numEntities = 4;
 }
 
diff --git a/otp/README.md b/otp/README.md
index 4e40da2..dc172b9 100644
--- a/otp/README.md
+++ b/otp/README.md
@@ -2,4 +2,4 @@ One time password generation
 
 # OTP Service
 
-Generate one time passwords (OTP) for any unique id, email or user. Codes are valid for up to 60 seconds.
+Generate one time passwords (OTP) for any unique id, email, or user. Codes have a user configurable expiry time.
diff --git a/otp/proto/otp.proto b/otp/proto/otp.proto
index ee97bc7..031be41 100644
--- a/otp/proto/otp.proto
+++ b/otp/proto/otp.proto
@@ -33,6 +33,6 @@ message ValidateRequest {
 }
 
 message ValidateResponse {
-	// returns true if successful
+	// returns true if the code is valid for the ID
 	bool success = 1;
 }
diff --git a/postcode/README.md b/postcode/README.md
index d5e1039..a669fa8 100644
--- a/postcode/README.md
+++ b/postcode/README.md
@@ -1,5 +1,5 @@
-Instant and fast postcode lookup
+Fast UK postcode lookup
 
 # Postcode Service
 
-Lookup postcodes for their related country, region and additional information.
+Lookup UK postcodes for their related latitude/longitude, region, and additional information.
diff --git a/postcode/proto/postcode.proto b/postcode/proto/postcode.proto
index dfd2c52..ecf0a63 100644
--- a/postcode/proto/postcode.proto
+++ b/postcode/proto/postcode.proto
@@ -33,7 +33,7 @@ message LookupResponse {
 	double longitude = 7;
 }
 
-// Validate a postcode. Should return valid: true or valid: false
+// Validate a postcode.
 message ValidateRequest {
 	// UK postcode e.g SW1A 2AA
 	string postcode = 1;
@@ -41,6 +41,7 @@ message ValidateRequest {
 }
 
 message ValidateResponse {
+	// Is the postcode valid (true) or not (false)
 	bool valid = 1;
 }
 
diff --git a/routing/README.md b/routing/README.md
index 4883a8b..8561d70 100644
--- a/routing/README.md
+++ b/routing/README.md
@@ -3,6 +3,6 @@ Etas, routes and turn by turn directions
 # Routing Service
 
 The routing service provides a faster and cheaper alternative to the Google Maps API. 
-Get etas, routes and turn by turn directions all from openstreetmap data. 
+Get etas, routes, and turn by turn directions all from OpenStreetMap data. 
 
 Powered by [OSRM](http://project-osrm.org/)
diff --git a/routing/proto/routing.proto b/routing/proto/routing.proto
index 7ab059a..394de95 100644
--- a/routing/proto/routing.proto
+++ b/routing/proto/routing.proto
@@ -56,7 +56,7 @@ message Direction {
 	repeated Intersection intersections = 7;
 }
 
-// Turn by turn directions from a starting and endpoint including maneuvers and bearings
+// Turn by turn directions from a start point to an end point including maneuvers and bearings
 message DirectionsRequest {
 	// The staring point for the journey
 	Point origin = 1;
@@ -81,7 +81,7 @@ message EtaRequest {
 	Point origin = 1;
 	// The end point for the eta calculation
 	Point destination = 2;
-	// type of transport e.g car, foot, bicycle
+	// type of transport. Only "car" is supported currently.
 	string type = 3;
 	// speed in kilometers
 	double speed = 4;
diff --git a/rss/README.md b/rss/README.md
index f36c976..25498b0 100644
--- a/rss/README.md
+++ b/rss/README.md
@@ -2,5 +2,5 @@ RSS feed crawler and reader
 
 # RSS Service
 
-Provides a simple way to crawl and index RSS feeds making them accessibly via a simple unified API.
+Provides a simple way to crawl and index RSS feeds making them accessible via a simple unified API.
 
diff --git a/rss/proto/rss.proto b/rss/proto/rss.proto
index b000e52..f1ffebd 100644
--- a/rss/proto/rss.proto
+++ b/rss/proto/rss.proto
@@ -41,7 +41,7 @@ message Entry {
 	string date = 7;
 }
 
-// Add a new RSS feed with a name, url and category
+// Add a new RSS feed with a name, url, and category
 message AddRequest {
 	// rss feed name
 	// eg. a16z
diff --git a/time/README.md b/time/README.md
index 47ad64d..0e8fd9b 100644
--- a/time/README.md
+++ b/time/README.md
@@ -1,7 +1,7 @@
-Time, date and timezone info
+Time, date, and timezone info
 
 # Time Service
 
-Get the time, date and timezone info for any given location in the world. 
+Get the time, date, and timezone info for any given location in the world. 
 
 Powered by [Weather API](https://weatherapi.com)
diff --git a/url/README.md b/url/README.md
index e45d9a1..a44f4a2 100644
--- a/url/README.md
+++ b/url/README.md
@@ -1,5 +1,5 @@
-URL shortening, sharing and tracking
+URL shortening, sharing, and tracking
 
 # URL Service
 
-The url service provides one time short urls for anything. Shorten, share and track the usage.
+The url service provides one time short urls for anything. Shorten, share, and then track the usage.
diff --git a/url/proto/url.proto b/url/proto/url.proto
index 181cb9c..a00e8d0 100644
--- a/url/proto/url.proto
+++ b/url/proto/url.proto
@@ -30,8 +30,7 @@ message URLPair {
 	int64 hitCount = 5;
 }
 
-// List shortened URLs. It has no input parameters, as it will take
-// the user ID from the token and list the user's (caller's) shortened URLs.
+// List information on all the shortened URLs that you have created
 message ListRequest {
 	// filter by short URL, optional
 	string shortURL = 2;
@@ -42,8 +41,6 @@ message ListResponse {
 }
 
 // Proxy returns the destination URL of a short URL.
-// Proxy resolves even URLs not owned by the token holder,
-// unlike the List endpoint.
 message ProxyRequest {
 	// short url ID, without the domain, eg. if your short URL is
 	// `m3o.one/u/someshorturlid` then pass in `someshorturlid`
diff --git a/user/proto/user.proto b/user/proto/user.proto
index 8ba9e00..d53a755 100644
--- a/user/proto/user.proto
+++ b/user/proto/user.proto
@@ -154,7 +154,7 @@ message LogoutResponse {
 
 // Verify the email address of an account from a token sent in an email to the user.
 message VerifyEmailRequest {
-        // The token from the verification email
+	// The token from the verification email
 	string token = 1;
 }
 
@@ -163,21 +163,22 @@ message VerifyEmailResponse{
 }
 
 // Send a verification email
-// to the user being signed up. Email from will be 'support@m3o.com',
+// to the user being signed up. Email from will be from 'support@m3o.com',
 // but you can provide the title and contents.
-// Use $micro_verification_link template variable in the content.
+// The verification link will be injected in to the email as a template variable, $micro_verification_link.
+// Example: 'Hi there, welcome onboard! Use the link below to verify your email: $micro_verification_link'
+// The variable will be replaced with an actual url that will look similar to this:
+// 'https://user.m3o.com/user/verify?token=a-verification-token&rediretUrl=your-redir-url'
+
 message SendVerificationEmailRequest{
 	string email = 1;
 	string subject = 2;
-	// Example: 'Hi there, welcome onboard! Use the link below to verify your email: $micro_verification_link'
-	// The variable will be replaced with an actual url that will look similar to this:
-	// 'https://user.m3o.com/user/verify?token=a-verification-token&rediretUrl=your-redir-url'
+	// Text content of the email. Don't forget to include the string '$micro_verification_link' which will be replaced by the real verification link
 	// HTML emails are not available currently.
 	string textContent = 3;
 	string redirectUrl = 4;
 	string failureRedirectUrl = 5;
-	// While the from email address can't be changed,
-	// the from name (ie. sender name) can.
+	// Display name of the sender for the email. Note: the email address will still be 'support@m3o.com'
 	string fromName = 6;
 }
 
diff --git a/weather/proto/weather.proto b/weather/proto/weather.proto
index ba69a51..48c36c0 100644
--- a/weather/proto/weather.proto
+++ b/weather/proto/weather.proto
@@ -61,7 +61,7 @@ message ForecastResponse {
 	string timezone = 6;
 	// the local time
 	string local_time = 7;
-	// forecase for the next number of days
+	// forecast for the next number of days
 	repeated Forecast forecast = 8;
 }