Use imperative present tense for synopsis

README.md

@@ -147,6 +147,11 @@ However, there is also a lot of prior art in our SDKs, so mention of particular
 Prefixes such as "Capability to" and "Support for" should generally be avoided, in particular at the start of the first sentence of any given synopsis.
 This is because the entire document is about capabilities to do "X", so additional wording such as "Capability for the application to do X" is superfluous and not helpful to the reader.
 
+Consistently use imperative, present tense where that makes sense (also known as 'imperative mood' in the context of git commit messages) - e.g.:
+
+- "Provide a literal token" rather than "Providing a literal token"
+- "Return continuous message history" rather than "Used to return continuous message history"
+
 As we evolve this work we can hopefully add to this guidance around what should be included and what should be avoided.
 
 ## Disincluded Features

sdk.yaml

@@ -3,7 +3,7 @@
 Agent Identifier:
   .specification: RSC7d
   .synopsis: |
-    Sends an `Ably-Agent` HTTP header for REST and Realtime Websocket connections,
+    Send an `Ably-Agent` HTTP header for REST and Realtime Websocket connections,
     identifying the library version,
     as well as relevant information describing any underlying layers and the client platform.
   Agents:
@@ -13,10 +13,10 @@ Agent Identifier:
       For use only by other Ably-authored SDKs, on a need-to-have basis.
   Operating System:
     .synopsis: |
-      Includes a product component indicating the runtime OS type and version.
+      Include a product component indicating the runtime OS type and version.
   Runtime:
     .synopsis: |
-      Includes a product component indicating the type of runtime, as discrete from the OS type.
+      Include a product component indicating the type of runtime, as discrete from the OS type.
       This does not always include a version (e.g. for `browser` runtime emitted by `ably-js`
       and the `uwp` runtime emitted by `ably-dotnet`).
 Authentication:
@@ -52,19 +52,19 @@ Authentication:
     Literal:
       .specification: [RSA4a, RSA4, RSC1, TO3j2, TO3j3]
       .synopsis: |
-        Providing a literal `token` or `tokenDetails` in client options.
+        Provide a literal `token` or `tokenDetails` in client options.
         Mostly only used for testing, since tokens are short-lived - this method does not provide the client library with a means to renew the token automatically when the previous one expires.
     URL:
       .specification:
         [RSA8c, TO3j6, TO3j7, TO3j8, TO3j9, AO2c, AO2d, AO2e, AO2f, RSA4]
       .synopsis: |
         `authUrl`, `authMethod`, `authHeaders` and `authParams`:
         Service `Auth#requestToken` calls by querying a provided URL (`authURL` client option) to obtain a token request, or the token itself.
-        Supports specification of other HTTP request properties (method, headers and params) using the `authMethod`, `authHeaders` and `authParams` client options respectively.
+        Support specification of other HTTP request properties (method, headers and params) using the `authMethod`, `authHeaders` and `authParams` client options respectively.
       Query Time:
         .specification: [TO3j10, RSA9d, RSA10k, AO2g]
         .synopsis: |
-          When issuing a token request, query the Ably service for the current time instead of relying on a locally-available time of day.
+          Query the Ably service for the current time instead of relying on a locally-available time of day when issuing a token request.
           Enabled using `queryTime` client option.
 Debugging:
   .synopsis: |
@@ -73,7 +73,7 @@ Debugging:
   Logs:
     .specification: [TO3b, TO3c]
     .synopsis: |
-      The level of log messages to generate and where to write them to, using the `logLevel` and `logHandler` client options.
+      Set the level of log messages to generate and where to write them to, using the `logLevel` and `logHandler` client options.
       Typically a handler/sink and a verbosity level, but some logging systems may express
       this differently for idiomatic reasons that make sense for the language, framework
       or runtime platform.
@@ -83,7 +83,7 @@ Protocol:
   JSON:
     .specification: [RSC8b, TO3f, G1]
     .synopsis: |
-      Encode and decode messages as [JSON](https://www.json.org/json-en.html),
+      Encode or decode messages as [JSON](https://www.json.org/json-en.html),
       overriding the default [MessagePack](https://msgpack.org/) by using the `useBinaryProtocol` client option.
   Maximum Message Size:
     .specification: [TO3l8, RSL1i, RTL6d1, CD2c]
@@ -92,7 +92,7 @@ Protocol:
   MessagePack:
     .specification: [RSC8a, RSL4c, G1]
     .synopsis: |
-      Encoding and decoding messages in binary format with [MessagePack](https://msgpack.org/).
+      Encode or decode messages in binary format with [MessagePack](https://msgpack.org/).
       MessagePack, often abbreviated to MsgPack, is the default for runtime environments that have a suitable level of support for binary data.
 Push Notifications:
   Activation:
@@ -186,14 +186,14 @@ Realtime:
     Encryption:
       .specification: [RTL16, TB2b, RTS3c]
       .synopsis: |
-        The option to configure a `cipher`, specifying encryption algorithm and attributes.
+        Configure a `cipher`, specifying encryption algorithm and attributes.
         Used for subscribe and publish on this channel.
     History:
       .documentation:
         - https://ably.com/docs/realtime/history
       .specification: [RTL10, CP2a, RTL15a]
       .synopsis: |
-        Used to return continuous message history up to the exact point a realtime channel was attached.
+        Retrieve continuous message history up to the exact point a realtime channel was attached.
         This includes both messages persisted for the default duration of two minutes, and messages persisted for 24-72 by enabling the `persist all messages` channel rule.
         Includes the capability to only retrieve messages prior to the moment that the channel was attached or emitted an `UPDATE` indicating loss of continuity.
     Mode:
@@ -217,29 +217,29 @@ Realtime:
       Enter:
         .specification: [RTP8, RTP10]
         .synopsis: |
-          Methods to enter and leave presence on channels for this client.
+          Enter or leave presence on channels for this client.
         Client:
           .specification: [RTP14, RTP15]
           .synopsis: |
-            Methods to enter and leave presence for a given `clientId`,
+            Enter or leave presence for a given `clientId`,
             not necessarily the id for this client.
       Get:
         .specification: RTP11
         .synopsis: |
-          Obtain a list of the current members of the channel, as a callback.
+          Obtain a list of the current members of the channel.
           Optional parameters include `waitForSync` (defaults to `true`), `clientId` and `connectionId`.
       History:
         .specification: RTP12
       Subscribe:
         .specification: [RTP6, RTP7]
         .synopsis: |
-          Methods to subscribe and unsubscribe for presence events on channels for this client.
+          Subscribe or unsubscribe for presence events on channels for this client.
       Update:
         .specification: RTP9
         Client:
           .specification: RTP15
           .synopsis: |
-            Method to update presence data and/or extras for a `clientId`,
+            Update presence data and/or extras for a `clientId`,
             not necessarily the id for this client.
     Publish:
       .specification: RTL6
@@ -255,20 +255,20 @@ Realtime:
       .specification:
         [RTL2, TH1, TH2, TH3, TH4, TH5, RTN11d, RTL4e, RTL3a, RTL4g, RTL14, RTL24, RTP5]
       .synopsis: |
-        `ChannelEvent` events can be received when channel state changes.
+        Receive `ChannelEvent` events when channel state changes.
         The current `ChannelState` can be queried (e.g. via a `state` property on the channel instance).
-        Also provides access to an error reason object when the channel is in a state of disruption (for example `FAILED`, `DETACHED` or `SUSPENDED`).
+        Also, access to an error reason object when the channel is in a state of disruption (for example `FAILED`, `DETACHED` or `SUSPENDED`).
     Subscribe:
       .specification: [RTL7, RTL8]
       .synopsis: |
-        Subscribe and unsubscribe for messages on channels for this client.
+        Subscribe or unsubscribe for messages on channels for this client.
       Deltas:
         .documentation:
           - https://ably.com/docs/realtime/channels/channel-parameters/deltas
           - https://ably.com/blog/message-delta-compression
         .specification: [RTL16, RTL18, RTL19, RTL20, PC1, PC2, PC3, TO3o, TM2i, TB2c, RTS3c]
         .synopsis: |
-          VCDiff-encoded delta streams.
+          Subscribe to and decode VCDiff-encoded delta streams.
           SDKs may choose to offer this only if a plugin is supplied via client options
           (optional functionality).
           Deltas are enabled for a channel by setting the `delta` channel parameter to `vcdiff` using the `setOptions` method on the channel.
@@ -300,7 +300,7 @@ Realtime:
     Ping:
       .specification: RTN13
       .synopsis: |
-        Sends a heartbeat message to the Ably service and returns the time taken to receive a corresponding heartbeat in response, or an error if the operation failed.
+        Send a heartbeat message to the Ably service and returns the time taken to receive a corresponding heartbeat in response, or an error if the operation failed.
         This can be useful for measuring true roundtrip client to Ably server latency for a simple message, or for checking that an underlying transport is responding currently.
     Recovery:
       .specification:
@@ -319,7 +319,7 @@ Realtime:
     State Events:
       .specification: [RTN4, RTN25]
       .synopsis: |
-        Mechanisms to get connection state, as well as to receive events when connection state changes.
+        Get connection state, as well as receive events when connection state changes.
         Also provides access to an error reason object in case of failure.
     Suspended Retry Timeout:
       .specification: [TO3l2, RTN14e]
@@ -367,7 +367,7 @@ REST:
     Encryption:
       .specification: [RSL7, TB2b, RSN3c]
       .synopsis: |
-        The option to configure a `cipher`, specifying encryption algorithm and attributes.
+        Configure a `cipher`, specifying encryption algorithm and attributes.
         Used for subscribe and publish on this channel.
         `AES` with `CBC`, `PKCS#7` with a default key length of 256 bits, as well as support for `AES128`.
     Existence Check:
@@ -386,7 +386,7 @@ REST:
       .synopsis: Enumerate local channel instances.
     Name:
       # to be formally specified: https://github.com/ably/docs/issues/1416
-      .synopsis: Read-only property containing the channel name.
+      .synopsis: Get the channel name.
     Presence:
       .specification: [RSL3, RSP1, RSP2]
       History:
@@ -404,13 +404,13 @@ REST:
           - https://ably.com/blog/introducing-idempotent-publishing
         .specification: [RSL1k, RTL6a1, TO3n]
         .synopsis: |
-          Makes REST publish operations idempotent.
+          Make REST publish operations idempotent.
           Enabled by default or can be disabled by setting the `idempotentRestPublishing` client option to `false`.
     Push Notifications:
       .specification: RSH7
       .synopsis: |
         Available on platforms that support receiving push notifications.
-        The `PushChannel` interface, which is made available via the `push` property on REST and Realtime channel instances.
+        A `PushChannel` interface, which is made available via the `push` property on REST and Realtime channel instances.
       List Subscriptions:
         .documentation: https://docs.ably.com/api/rest-api/#list-channel-subscriptions
         .specification: RSH7e
@@ -441,12 +441,12 @@ REST:
   Opaque Request:
     .specification: [RSC19, RTC9]
     .synopsis: |
+      Provides a function to issue HTTP REST requests to the Ably endpoints with all the built in functionality of the library such as authentication, pagination, fallback hosts, MessagePack and JSON support etc..
       Convenience for customers who wish to use REST API functionality that is either not documented or is not included in the API for our client libraries.
-      The REST client library provides a function to issue HTTP requests to the Ably endpoints with all the built in functionality of the library such as authentication, pagination, fallback hosts, MessagePack and JSON support etc..
   Request Identifiers:
     .specification: [RSC7c, TO3p]
     .synopsis: |
-      Adds a query string parameter, based on a source of randomness, to all REST requests.
+      Add a query string parameter, based on a source of randomness, to all REST requests.
       Enabled using the `addRequestIds` client option.
   Request Timeout:
     .specification: TO3l4
@@ -525,7 +525,7 @@ Transport:
       the timeout for opening the connection, available in the client library if supported by the transport.
   HTTP/2:
     .synopsis: |
-      Handles connectivity to an HTTP/2 endpoint, with the ability to fallback to using HTTP/1.1 if the endpoint doesn't support HTTP/2.
+      Handle connectivity to an HTTP/2 endpoint, with the ability to fallback to using HTTP/1.1 if the endpoint doesn't support HTTP/2.
   Maximum Frame Size:
     .specification: [TO3l9, CD2d]
     .synopsis: |