Apply suggestions from code review

Co-authored-by: Andres Uribe <[email protected]>

doc/howto/credential.md

@@ -4,7 +4,7 @@
 
 A [Verifiable Credential (VC)](https://www.w3.org/TR/vc-data-model/) is a standard format to package a set of claims that an _issuer_ makes about a _subject_. The Verifiable Credentials Data Model, a W3C standard, introduces a number of concepts, most notable among them, the [three party model](https://www.w3.org/TR/vc-data-model/#ecosystem-overview) of **issuers**, **holders**, and **verifiers**. The model is a novel way of empowering entities to have tamper-evident representations of their data which acts as a mechanism to present the data to any third party (a verifier) without necessitating contact between the verifier and issuer. With the three party model entities are given more [control, transparency, privacy, and utility](https://www.lifewithalacrity.com/2016/04/the-path-to-self-soverereign-identity.html) for data that is rightfully theirs.
 
-VCs are defined by a data model, which does not provide guidance on transmitting or sharing credentials between parties (protocols). The data model also does not provide guidance on _securing_ the credential (which puts the verifiable in verifiable credential). There are two prominent options here: [Data Integrity](https://w3c.github.io/vc-data-integrity/) and [JWT](https://w3c.github.io/vc-jose-cose/) both of which we have demonstrated support for. The data model has a number of required (core) properties, and multiple means of extension to meet many use cases and functional needs.
+VCs are defined by a data model, which does not provide guidance on transmitting or sharing credentials between parties (protocols). The data model also does not provide guidance on _securing_ the credential (which puts the verifiable in verifiable credential). There are two prominent options here: [Data Integrity](https://www.w3.org/TR/vc-data-integrity/) and [JOSE/COSE](https://www.w3.org/TR/vc-jose-cose/) both of which we have demonstrated support for. The data model has a number of required (core) properties, and multiple means of extension to meet many use cases and functional needs.
 
 ## VCs in the SSI Service
 
@@ -34,7 +34,7 @@ We get back a response with the `id` as `did:key:z6Mkm1TmRWRPK6n21QncUZnk1tdYkje
 
 ### 2. Create a person schema
 
-Because we want to include information about the subject in the credential, let's first create a schema to define the shape of the credential's data with required `firstName` and `lastName` values.
+Because we want to include information about the subject in the credential, let's first create a schema to define the shape of the credential's data with required `firstName` and `lastName` values. While this step is optional, it's a good practice to have a schema that describes the shape of the data.
 
 Once we have our schema, we'll submit it to the service with a `PUT` request to `v1/schemas` as follows:
 
@@ -70,7 +70,7 @@ Separately, we've figured out that the subject we're creating the credential for
 
 Construct a `PUT` request to `/v1/credentials` as follows:
 
-```
+```bash
 curl -X PUT localhost:3000/v1/credentials -d '{
   "issuer": "did:key:z6Mkm1TmRWRPK6n21QncUZnk1tdYkje896mYCzhMfQ67assD",
   "verificationMethodId": "did:key:z6Mkm1TmRWRPK6n21QncUZnk1tdYkje896mYCzhMfQ67assD#z6Mkm1TmRWRPK6n21QncUZnk1tdYkje896mYCzhMfQ67assD",
@@ -109,7 +109,7 @@ Upon success we'll see a response such as:
 }
 ```
 
-In the `credential` property we see a readable version of the VC. The VC is signed and packaged as a JWT in the `credentialJwt` property. If you're interested, you can decode the JWT using a tool such as [jwt.io](https://jwt.io/). If you were to 'issue' or transmit the credential to a _holder_ you would just send this JWT value.
+In the `credential` property we see an unsecured, but readable, version of the VC. The VC is signed and packaged as a JWT in the `credentialJwt` property. If you're interested, you can decode the JWT using a tool such as [jwt.io](https://jwt.io/). If you were to 'issue' or transmit the credential to a _holder_ you would just send this JWT value.
 
 ## Getting Credentials