Apply suggestions from code review

Co-authored-by: Lucas Tortora <[email protected]>

docs/build/identity.rs/1.1/docs/contact.mdx

@@ -13,5 +13,5 @@ If you found a security related issue, please follow the [responsible disclosure
 
 For everything else, you can get in contact with the project by:
 
-- Filing an issue on [GitHub](https://github.com/iotaledger/identity.rs).
+- Creating an [issue](https://github.com/iotaledger/identity.rs/issues/new/choose) on [GitHub](https://github.com/iotaledger/identity.rs).
 - Joining the `identity` channel on the [IOTA Discord](https://discord.iota.org/).

docs/build/identity.rs/1.1/docs/contribute.mdx

@@ -38,12 +38,12 @@ This documentation is also open source and hosted on GitHub.
 
 If you want to contribute new documentation or fix an error, see the [contribution guidelines](https://github.com/iotaledger/iota-wiki/blob/main/.github/CONTRIBUTING.md).
 
-## Share your Knowledge
+## Share Your Knowledge
 
 Helping others is an important part of any open source ecosystem.
 
 By sharing your knowledge with others, you can provide a lot of value to the community and maybe inspire someone else to learn and contribute.
 
-Take a look at what discussions are going on in the #identity-discussion channel on [Discord](https://discord.iota.org).
+Take a look at what discussions are going on in the `#identity-discussion` channel on [Discord](https://discord.iota.org).
 
 Thanks :heart:

docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx

@@ -15,7 +15,7 @@ keywords:
 
 :::info TL;DR
 
-The IOTA DID method users Alias Outputs for storing DID Documents.
+The IOTA DID method uses Alias Outputs for storing DID Documents.
 Alias Outputs are created via transactions,
 and require a [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/) to cover the data storage.
 The deposit is refundable upon destruction of the output.
@@ -30,36 +30,35 @@ The IOTA DID method uses the IOTA ledger, which is baed on the unspent transacti
 as well as the features of the [Stardust](/introduction/stardust/explanations/what_is_stardust) upgrade,
 which are fundamental to the IOTA DID method.
 
-The Alias _Output_ is used to store a DID Document on the ledger.
+The Alias Output is used to store a DID Document on the ledger.
 It is a specific implementation of the UTXO _state machine_ that can hold arbitrary data in its `State Metadata`.
 The Alias Output has two kinds of controllers, a state controller and a governor.
 
-A state controller can execute a state transition which allows updating the data in the `State Metadata`.
+The state controller can only execute state transitions, which update the data in the `State Metadata`.
 
-The governor, on the contrary, can't update the `State Metadata` but can change both controllers and destroy the Alias Output.
+The governor, on the contrary, can't update the `State Metadata` but can change controllers and even destroy the Alias Output.
 
-A controller can be either Ed25519 Address, [Alias Address or an _NFT_ Address](/learn/protocols/stardust/core-concepts/multi-asset-ledger/)
-and at most one of each can be set for an Alias Output.
+A controller can be either Ed25519 Address, [Alias Address or an _NFT_ Address](/learn/protocols/stardust/core-concepts/multi-asset-ledger/). Only one of each of these types can be set for an Alias Output.
 
-In order to create a new Alias Output, a transaction must be made that includes another Output, for example,
-a Basic Output, as input and the new Alias Output, along with other outputs if needed, as outputs.
+To create a new Alias Output, a transaction must be made that includes another Output as input,
+a Basic Output, for example, and the new Alias Output as output.
 
 ### Storage Deposit
 
 The arbitrary data stored in the `State Metadata` of the Alias output must be covered by a
 [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/).
 This helps to control the ledger size from growing uncontrollably while guaranteeing the data
-is indefinitely stored on the ledger which is important for resolving DID Documents.
+is indefinitely stored on the ledger, which is important for resolving DID Documents.
 This deposit is fully refundable and can be reclaimed when the output is destroyed.
 
 Both the state controller and the governor can control the tokens stored in the Alias Output.
 _Nodes_ expose an API to calculate the required deposit depending on the size of the data stored.
 
 ### Alias ID
 
-Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates a new Alias Output.
-The actual DID is derived from this `Alias ID`, hence it will be unknown before publishing the transaction.
-Consequently, the DID inside the `State Metadata` will be replaced by the placeholder `did:0:0` to indicate self.
+Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates the Alias Output.
+The actual DID is derived from this `Alias ID`, so it will be unknown before publishing the transaction.
+Consequently, the DID inside the `State Metadata` is replaced by the placeholder `did:0:0` to indicate self.
 
 If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs.
 This feature is necessary for updating the DID Documents since the DID itself is derived from the `Alias ID`.

docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx

@@ -24,9 +24,9 @@ while facilitating encrypted communication.
 
 
 A DID is a unique identifier that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. DIDs are the fundamental building blocks of decentralized digital identity.
-This implementation complies to the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C).
+This implementation complies with the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C).
 
-In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they also want to use the `iota` method name. Libraries implementing the `iota` DID Method Specification are provided for [Rust](../getting-started/rust.mdx) and [WASM](../getting-started/wasm.mdx).
+In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they want to use the `iota` method name. Libraries implementing the `iota` DID Method Specification are provided for [Rust](../getting-started/rust.mdx) and [WASM](../getting-started/wasm.mdx).
 
 An example of a DID conforming to the `iota` method specification:
 `did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe`
@@ -65,8 +65,12 @@ Please read or view some materials on the subject before continuing.
 
 :::
 
+### DID Document Anatomy
+
 A DID Document mostly contains two important pieces of data: verification methods and services.
 
+#### Verification Methods
+
 Verification methods contain public key material that can be used to prove ownership over the identity,
 by cryptographically signing something with the associated private key.
 The public key can be used to verify that the identity subject signed the data and therefore controls the private key.
@@ -82,6 +86,8 @@ This may lead to loss of funds or control over your own digital identity.
 
 :::
 
+#### Services
+
 Services are URIs that point to more information about the identity.
 This could be something as simple as a website for an organizational identity.
 These services are publicly available for all to read,
@@ -92,14 +98,16 @@ and should not contain Personal Identifiable Information (PII) in the case of hu
 DIDs allow any subject to have a unique identifier that they can prove ownership of,
 and at the same time provide a way to send them encrypted messages.
 The Identity is Self-Sovereign, meaning the subject is always in control;
-whether it is creating, updating or destroying it.
+whether it is [creating](../how-tos/decentralized-identifiers/create.mdx), [updating](../how-tos/decentralized-identifiers/update.mdx), or [destroying](../how-tos/decentralized-identifiers/destroy.mdx) it.
+
+### Verifiable Credentials
 
 DIDs become more interesting when you combine them with [verifiable credentials (VC)](verifiable-credentials.mdx).
 In essence, verifiable credentials (VCs) are signed statements by trusted third parties about a certain identity.
 The signer, or Issuer, is referenced by the DID and so is the subject, often called the holder.
 The holder controls a copy of this statement and can share it with other parties, the _Verifiers_,
-that can verify the statement and check which party made the statement, without having to ask the Issuer.
-Instead, they can verify the signature of the issuer by checking the issuers DID Document.
+who can verify the statement and check which party made the statement without asking the Issuer.
+Instead, they can verify the issuer's signature by checking the issuer's DID Document.
 
 This puts Holders back in control over their own data,
 while making the data much more trustworthy as it has become verifiable.
@@ -114,11 +122,11 @@ Inherently, IOTA provides some unique features that have a major impact on the u
 DID Documents are stored in the ledger state and are covered [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/).
 This guarantees that all nodes will have an up-to-date copy of the latest DID Document.
 Resolving a DID into its document can usually be done by any IOTA node in the network.
-This solves many issues regarding availability, accessibility or synchronization.
+This solves many issues regarding availability, accessibility, and synchronization.
 
 ### Layer1 Interactions
 
-DID Document are stored in an [Alias Outputs](./about-alias-outputs.mdx),
+DID Documents are stored in [Alias Outputs](./about-alias-outputs.mdx),
 this allows them to directly interact with Layer 1 artifacts like [NFTs and native assets](/learn/protocols/stardust/core-concepts/multi-asset-ledger/).
 
 For instance, an Alias Output representing a DID can hold native assets or control NFTs.

docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx

@@ -25,7 +25,7 @@ Verifiable credentials (VCs) are statements (e.g., Alice has a driver's license)
 that can be cryptographically verified by a third party, either online or in person.
 Additionally, the holder of the VC decides what is shared and who it is shared with.
 
-There are several types of actors that play different roles in a verifiable credential system.
+There are several types of actors that play different roles in a Verifiable Credential system.
 We'll start with a common example of how things work in the world today using physical credentials and centralized databases,
 and outline the roles that various entities play in the Verifiable Credential system.
 
@@ -38,13 +38,13 @@ who can verify that Alice (the _subject_) is indeed a citizen.
 
 
 
-**Subject:** An entity about which claims are made – Alice (the _subject_) is a citizen of this country.
+**Subject:** An entity about which claims are made – in this example, that Alice (the _subject_) is a citizen of this country.
 
-**Holder:** An entity which possesses verifiable credentials – Alice (the _Holder_) possesses the passport (the _VC_).
+**Holder:** Any entity with a verifiable credential – Alice (the _Holder_) possesses the passport (the _VC_).
 
 **Issuer:** An entity which asserts claims about a subject – The governing body (the _issuer_), which is trusted, issues Alice a passport.
 
-**Verifier:** An entity which check's if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _issuer_) which issued Alice her passport, and validates that Alice (the _subject_) is a citizen.
+**Verifier:** An entity which checks if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _issuer_) which issued Alice her passport and validates that Alice (the _subject_) is a citizen.
 
 :::note
 
@@ -54,21 +54,21 @@ See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github
 
 ## Verifiable Credentials in IOTA
 
-In the IOTA Identity framework, instead of a physical passport being given to Alice with the information being written
+In the IOTA Identity framework, instead of a physical passport being given to Alice and its information written
 into a centralized database owned by the government, Alice receives a digital verifiable credential,
 and the information required for verification in the future is written to the Tangle.
 
 At a high level, the creation and verification of a VC on IOTA works as follows:
 
 
-The first step is to create a verifiable credential which requires the subject (Alice) and issuer (the government) to
-have [DIDs](./decentralized-identifiers.mdx) published on the Tangle, and a set of statements being asserted (that Alice has a passport).
+The first step is to create a verifiable credential that requires the subject (Alice) and issuer (the government) to
+have [DIDs](./decentralized-identifiers.mdx) published on the Tangle and a set of statements being asserted (that Alice has a passport).
 The issuer signs the credential with their private key and publishes the public key to the Tangle.
 
-Once the issuer is confident that the credential satisfies its expectation,
+Once the issuer is confident that the credential satisfies its expectations,
 the credential is stored and transmitted to the subject in a secure manner (off-chain).
 
 Validation is performed by looking up the issuer's public key on the Tangle,
 the holder proving ownership of their DID to the verifier (evidence),
-and validating that the credential has indeed been signed by the issuing party.
+and validating that the issuing party has indeed signed the credential.
 

docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx

@@ -3,10 +3,10 @@
 A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx).
 It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation).
 
-For instance: after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
+For instance, after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
 the holder stores it securely until asked to present it.
 A company could then request proof of that university degree: the holder can [create a verifiable presentation](./../how-tos/verifiable-credentials/create.mdx)
-containing their credential, which is already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc).
+containing their credential, already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc).
 
 Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/).
 
@@ -20,7 +20,7 @@ See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/
 
 ### Replay Attacks
 
-A verifiable presentation without a challenge could potentially be stored by a malicious actor
+A malicious actor could potentially store a verifiable presentation without a challenge
 and replayed to a different verifier, impersonating the holder.
 This is because the holder's signature on a presentation would still be seen as valid indefinitely,
 until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used.
@@ -35,5 +35,5 @@ The challenge string should be sufficiently random and unique for each verifiabl
 being predicted. 
 
 Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as
-per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property,
+per `JwtPresentationOptions`. However, verifiers and different implementations could ignore that property,
 so setting a signature expiration alone should not be relied upon.