Merge pull request #45 from swcurran/tech-writer

Abstract and Overview cleanups from a real tech writer

spec/abstract.md

@@ -2,33 +2,32 @@
 
 The `did:tdw` (Trust DID Web) method is an enhancement to the
 `did:web` protocol, providing a complementary web-based DID method that addresses limitations
-of `did:web`. It's features include the following.
+of `did:web`. Its features include:
 
 - Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of,
   or alongside a `did:web` DID/DIDDoc.
-- Uses the same DID-to-HTTPS transformation as `did:web`.
-- Provides resolvers the full history of the DID using a verifiable chain of
+- The same DID-to-HTTPS transformation as `did:web`.
+- The ability to resolve the full history of the DID using a verifiable chain of
   updates to the DIDDoc from genesis to deactivation.
 - A [[def: self-certifying identifier]] (SCID) for the DID that is globally
-  unique and derived from the initial DIDDoc that enables DID portability, such
+  unique and derived from the initial DIDDoc which enables DID portability, such
   as moving the DIDs web location (and so the DID string itself) while retaining
   the DID's history.
-- DIDDoc updates include a proof signed by the DID Controller(s) *authorized* to
+- DIDDoc updates that include a proof signed by the DID Controller(s) *authorized* to
   update the DID.
 - An optional mechanism for publishing "pre-rotation" keys to prevent loss of
   control of the DID in cases where an active private key is compromised.
-- DID URL path handling that defaults (but can be overriden) to automatically
-  resolving `<did>/path/to/file` by using a comparable DID-to-HTTPS translation
-  as for the DIDDoc.
-- A DID URL path `<did>/whois` that defaults to automatically returning (if
+- DID URL path handling that defaults (but can be overridden) to automatically
+  resolve `<did>/path/to/file` by the same DID-to-HTTPS translation.
+- A DID URL path `<did>/whois` that defaults to automatically return (if
   published by the DID controller) a [[ref: Verifiable Presentation]] containing
   [[ref: Verifiable Credentials]] with the DID as the `credentialSubject`,
   signed by the DID.
 
 Combined, the additional features enable greater trust and security without
 compromising the simplicity of `did:web`. The incorporation of the DID Core
 compatible "/whois" path, drawing inspiration from the traditional WHOIS
-protocol [[spec:rfc3912]], offers an easy to use, decentralized, trust registry.
+protocol [[spec:rfc3912]], offers an easy-to-use, decentralized, trust registry.
 The `did:tdw` method aims to establish a more trusted and secure web environment by
 providing robust verification processes and enabling transparency and
 authenticity in the management of decentralized digital identities.

spec/overview.md

@@ -4,7 +4,7 @@ The evolution of [[ref: Decentralized Identifiers]] ([[ref: DID]]) continues to
 be a dynamic area of development in the quest for secure and private digital
 identity management. The `did:web` method, praised for its simplicity and ease
 of deployment, allows for DIDs to be associated with a domain's reputation or
-published on platforms like GitHub. However, it is not without its challenges
+published on platforms such as GitHub. However, it is not without its challenges--
 from trust layers inherited from the web and the absence of a verifiable history
 for the DID. Addressing these concerns, the proposed `did:tdw` (Trust DID Web)
 method aims to enhance `did:web` by introducing a verifiable history feature,
@@ -40,14 +40,15 @@ DID. For resolvers that want more assurance, `did:tdw` provides a way to "trust
 did:web" (or to enable a "trusted web" if you say it fast) enabled by the
 features listed in the [Abstract](#abstract).
 
-The following is a `tl;dr` summary of how `did:tdw` works.
+The following is a `tl;dr` summary of how `did:tdw` works:
 
-1. In the same path as where DID resolvers find a `did:web`'s `did.json`,
-  `did:tdw`'s `did.jsonl` ([[ref: JSON Lines]]) file is found. The same `did:web` DID-to-HTTPS
-  transformation is used.
+1. `did:tdw` uses the same DID-to-HTTPS tranformation as `did:web`, so
+   `did:tdw`'s  `did.jsonl` ([[ref: JSON Lines]]) file is found in the same
+   location as `did:web`'s `did.json` file.
 2. The `did.jsonl` is a list of JSON [[ref: DID log entries]], one per line,
-  whitespace removed, each of which contains the information needed to derive a
-  version of the DIDDoc from its preceding version.
+  whitespace removed (per [[ref: JSON Lines]]), each of which contains the
+  information needed to derive a version of the DIDDoc from its preceding
+  version.
 3. Each entry includes six JSON entries:
     1. A hash of the entry.
     2. The `versionId` of the DIDDoc, starting from 1 and incrementing.
@@ -91,12 +92,12 @@ The following is a `tl;dr` summary of how `did:tdw` works.
 An example of a `did:tdw` evolving through a series of versions can be seen in
 the [did:tdw Examples](#didtdw-example) of this specification.
 
-This draft specification was developed in parallel with the development of two proof
-of concept implementations. The specification/implementation interplay helped
-immensely in defining a practical, easy to use, easy to understand, DID method.
-The existing proof of concept implementations of the `did:tdw` DID Method are
-listed in the [Implementors Guide](#Implementations). The current Typescript
-implementation is less than 1000 lines of Typescript code.
+This draft specification was developed in parallel with the development of two
+proof of concept implementations. The specification/implementation interplay
+helped immensely in defining a practical, intuitive, straightforward, DID
+method. The existing proof of concept implementations of the `did:tdw` DID
+Method are listed in the [Implementors Guide](#Implementations). The current
+Typescript implementation is less than 1000 lines of Typescript code.
 
 ### The `/whois` Use Case