updates to APDU docs

docs/users-manual/yubikey-reference/apdu.md

@@ -18,28 +18,37 @@ limitations under the License. -->
 
 # APDUs
 
-An Application Protocol Data Unit (APDU) is simply a byte array that contains
+An Application Protocol Data Unit (APDU) is a byte array that contains
 information following the ISO 7816 standard. There are two kinds of APDU:
 
 * Command
 * Response
 
 The application running on the host machine (in PIV, that is "Off-Card") sends a Command
-APDU, and the YubiKey returns a response APDU.
+APDU to the YubiKey, and the YubiKey returns a response APDU.
 
-Here is an example of a command APDU, and its and response.
+A command APDU and its response can look like the following:
 
-```C
+```text
 command APDU:   00 87 03 9B 04 7C 02 80 00
 response APDU:  7C 0A 80 08 3D 12 D6 71 F7 32 75 0D 90 00
 ```
 
 ## Command APDU
 
-There are up to seven elements in a command APDU. All command APDUs must have the first
-four, but it is legal to have the first four, five, six, or seven elements.
+There are up to seven elements in a command APDU: 
+
+- Class (CLA)
+- Instruction (INS)
+- Parameter 1 (P1) 
+- Parameter 2 (P2) 
+- Length of Data (Lc)
+- Data 
+- Maximum Length of Response Data (Le)
 
-#### Table 1.1: Possible command APDU elements
+CLA, INS, P1, and P2 are required for all command APDUs; Lc, Data, and Le are optional.
+
+#### Table 1.1: Acceptable command APDU configurations
 
 | Class | Instruction | Param 1 | Param 2 | Length of Data |   Data   | Max Length of Response Data |
 |:-----:|:-----------:|:-------:|:-------:|:--------------:|:--------:|:---------------------------:|
@@ -48,32 +57,38 @@ four, but it is legal to have the first four, five, six, or seven elements.
 |  CLA  |     INS     |   P1    |   P2    |       Lc       | (absent) |          (absent)           |
 |  CLA  |     INS     |   P1    |   P2    |    (absent)    | (absent) |          (absent)           |
 
-For example, with the command APDU `00 87 03 9B 04 7C 02 80 00`, these are the elements.
+For example, with the command APDU `00 87 03 9B 04 7C 02 80 00`, these are the elements:
 
 #### Table 1.2: Example command APDU elements
 
 | CLA | INS | P1 | P2 | Lc |    Data     |    Le    |
 |:---:|:---:|:--:|:--:|:--:|:-----------:|:--------:|
 | 00  | 87  | 03 | 9B | 04 | 7C 02 80 00 | (absent) |
 
-When building command APDUs in the SDK, the `Le` value will always be absent. The `Le`
-value is the maximum number of bytes in the data response. However, we will not specify
-that. Rather, we will let the YubiKey return as many bytes as it will, and check the
+### Recommended implementation with the SDK
+
+When building command APDUs in the SDK, we recommend leaving the `Le` value absent. This allows us to let the YubiKey return as many bytes as it will and check the
 length in each command class.
 
 For example, when getting the version, we expect the return data to contain three bytes.
-We could set `Le` to 3. If so, then the class that actually sends the APDU (a
+If we set `Le` to 3, the class that actually sends the APDU (a
 `Connection` class) could check the length of the return data for an appropriate
-length. It could throw an exception or return an error.
+length and throw an exception or return an error in the case of a mismatch.
 
 However, we will instead make that check in the class that processes the specific
 command. In that way, if there is an error, the exception or error return can be
 generated by the class that knows what the command really is and create a more specific
-error message.
+and actionable error message.
 
 ## Response APDU
 
-A response APDU consists of up to three elements.
+A response APDU consists of up to three elements:
+
+- Data
+- Status Word 1 (SW1)
+- Status Word 2 (SW2)
+
+The last two bytes of a response APDU are the status word (composed of SW1 and SW2), which contains the error or success code. A response APDU might contain data and the status word or just the status word.
 
 #### Table 2.1: Possible response APDU elements
 
@@ -82,23 +97,20 @@ A response APDU consists of up to three elements.
 | Return Data |      SW1      |      SW2      |
 |  (absent)   |      SW1      |      SW2      |
 
-The last two bytes make up the status word, which is the error or success code. A
-response might contain data and the status word, or just the status word.
-
 For example, with the response APDU `7C 0A 80 08 3D 12 D6 71 F7 32 75 0D 90 00`, these
-are the elements.
+are the elements:
 
 #### Table 2.2: Example response APDU elements
 
 |                Data                 | SW1 | SW2 |
 |:-----------------------------------:|:---:|:---:|
 | 7C 0A 80 08 3D 12 D6 71 F7 32 75 0D | 90  | 00  |
 
-Note that if there is an error, the response APDU will be two bytes only: SW1 and SW2.
+If there is an error, the response APDU will be two bytes only: SW1 and SW2.
 For example, the two-byte response of `6A 81` means "Card is blocked or command not
 supported".
 
-#### Table 2.3: Response APDU indicating error
+#### Table 2.3: Example response APDU indicating error
 
 |   Data   | SW1 | SW2 |
 |:--------:|:---:|:---:|
@@ -107,9 +119,9 @@ supported".
 It is also possible to have a successful response APDU of only two bytes (no data). For
 example, suppose a command APDU requests the YubiKey set the number of PIN retries to
 five (instead of the default three). If the YubiKey successfully sets the retry count,
-there is no data to be returned, simply the status word, `90 00`, indicating success.
+there is no data to be returned, only the status word indicating success (`90 00`).
 
-#### Table 2.4: Response APDU indicating success with no data
+#### Table 2.4: Example response APDU indicating success with no data
 
 |   Data   | SW1 | SW2 |
 |:--------:|:---:|:---:|