Update hex-format.md

Author: Gadgetoid

software/hex-format.md

@@ -13,23 +13,27 @@ review-with: carlospa
 
 The .hex file is in [intel-hex format](https://en.wikipedia.org/wiki/Intel_HEX). Intel hex consists of records of data, with the address in memory to store the data at the start. All data is hex-ascii encoded. All lines start with a : character. All lines end with a checksum byte that can be used to verify the integrity of the data.
 
-A micro:bit .hex file usually starts writing data to the same fixed location in memory, so depending on the toolchain, we might expect the first line of the file to start like this:
+A micro:bit .hex file usually starts writing data to the same fixed location in memory. Depending on the toolchain, we might expect the first line of the file to start like this:
 
 :020000040000FA
 
 ## Universal Hex files
 
-The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit <span class="v1">v1</span> and micro:bit <span class="v2">V2</span>, in a format that DAPLink can process to only write to memory the data relevant to its micro:bit board.
+The latest board revision introduces a superset of the Intel-Hex format that enables compatibility across processor variants. A Universal Hex is a file that contains the binary data for both micro:bit <span class="v1">v1</span> and micro:bit <span class="v2">V2</span>, in a format that DAPLink can process and write to memory only the data relevant to its micro:bit board.
 
 A **Universal Hex** hex file will work on a v1 or V2 board. 
-A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size.
+A clear indication that you are working with this format is that the compiled .hex file will be ~1.8Mb instead of ~700Kb in size.
 
-A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/).
+The following resources will help you implement **Universal Hex** support in your application:
+
+* [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) 
+* [Detailed specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/).
 
 ### Cross device compatibility
-The Universal Hex format has been developed to ensure the best experience for users when moving between board variants. If a V1 only .hex is detected on a V2 board it will throw an error, but a V2 only hex will fail silently on a V1. This is very confusing to users and should be avoided.
 
-There may be cases where it is not possible to support both boards, for example an accessory that is designed only to target the V2 board variant. In these cases, to ensure the best user experience when flashing a hex file to any board variant, the file should always include an error message to signify board incompatibility to the user.
+Including *both* .hex formats within a Universal Hex ensures the best experience for users when moving between board variants. If a V1 only .hex is detected on a V2 board it will throw an error, but a V2 only hex will fail silently on a V1. This is confusing to users and should be avoided.
+
+There may be cases where it is not possible to support both boards, for example an accessory that targets only the V2 board variant. In these cases, to ensure the best user experience when flashing a hex file to any board variant, the file should always include an error message to signify board incompatibility to the user.
 
 We have created a [standalone error hex](/docs/software/assets/stand-alone-error-v1.hex) that can be combined with a V2 only hex to produce a Hex that will work on a V2 board, but error if used on a v1.
 
@@ -42,7 +46,7 @@ This example shows the worst, best and acceptable (when support for V1 is imposs
 
 These examples show the process of creating a Universal Hex. A V1 and V2 hex can be combined to produce a Universal Hex. If you can only support a V2 board,the standalone error can be combined with a V2 hex to produce a hex that will fail with an error on a V1 board, rather than failing silently.
 
-|Universal Hex format                                                 |V2 only Hex format                               |
+|Universal Hex format                                       |V2 only Hex format                                         |
 |-----------------------------------------------------------|-----------------------------------------------------------|
 | ![Universal Hex error 2](/docs/software/assets/uhex2.png) | ![Universal Hex error 3](/docs/software/assets/uhex1.png) |
 
@@ -53,8 +57,8 @@ If you are building .hex files for both board variants, you will need to use the
 
 See the [Micropython Hex file reference](https://microbit-micropython.readthedocs.io/en/latest/devguide/hexformat.html) for up to date information.
 
-MicroPython builds take a firmware.hex image (the MicroPython pre-compiled image) and appends your script to the end of it, in a fixed 8K region at a known address. When MicroPythons starts to run on the micro:bit, it looks for a signature at this fixed location, and uses that to determine whether to run the script, or drop directly to the REPL prompt.
+MicroPython builds take a "firmware.hex" image (the MicroPython pre-compiled image) and appends your script to the end of it, in a fixed 8K region at a known address. When MicroPythons starts to run on the micro:bit, it looks for a signature at this fixed location, and uses that to determine whether to run the script, or drop directly to the REPL prompt.
 
 ## Microsoft MakeCode Editor
 
-Hex files generated by the [MakeCode Editor](https://makecode.microbit.org) have embedded meta-data inside the .hex file. This is a [JSON encoded blob with various data about the script](https://github.com/Microsoft/pxt/blob/437f53ca6311335c7f3f75a062ec1079b4e7806a/docs/source-embedding.md), and also the source code program. This may be compressed, and it is stored inside the flash memory of the micro:bit (but only if space is available in the flash memory). But it is always inside the .hex file. This embedded source code program ensures that when you drag and drop the .hex file onto the originating editor, it can recover the source program again.
+Hex files generated by the [MakeCode Editor](https://makecode.microbit.org) include the source code of the program in addition to embedded metadata. This metadata comprises a [JSON encoded blob with information about the script](https://github.com/Microsoft/pxt/blob/437f53ca6311335c7f3f75a062ec1079b4e7806a/docs/source-embedding.md). Both the metadata and source code may be compressed and, space permitting, are stored inside the flash memory of the micro:bit. When you drag and drop a MakeCode .hex file onto the originating editor it can recover the source code, allowing the program to be modified and saved back to a .hex.