docs: Improve the intro sections.

Author: microbit-carlos

README.md

@@ -2,13 +2,18 @@
 
 [![CircleCI](https://circleci.com/gh/microbit-foundation/microbit-universal-hex.svg?style=svg)](https://circleci.com/gh/microbit-foundation/microbit-universal-hex)
 
-TypeScript/JavaScript library to create micro:bit Universal Hexes.
+TypeScript/JavaScript library to create micro:bit Universal Hex files for
+micro:bit.
 
 <img width="50%" alt="microbit-universal-hex logo" src="docs/img/microbit-uh-logo.png">
 
+The Universal Hex file format was created to be able to contain the binary data
+for micro:bit V1 and V2 boards in a single file, so that it works in all
+versions of the micro:bit.
+
 ## Documentation
 
-A raw draft of the docs can be found in
+The documentation can be found in
 https://microbit-foundation.github.io/microbit-universal-hex/.
 
 ## Web Tool
@@ -17,7 +22,7 @@ An implementation example can be found in the
 [docs/examples/webtool.html](docs/examples/webtool.html) file. This web tool can
 generate a Universal Hex from two Intel Hex files.
 
-It can be accessed online via:
+It can be accessed online on this URL:
 https://tech.microbit.org/software/universal-hex-creator/
 
 ## License

docs/_config.yml

@@ -13,7 +13,7 @@ exclude:
 
 # Just The Docs settings
 
-logo: 'docs/img/microbit-uh-logo-text.png'
+logo: 'img/microbit-uh-logo-text.png'
 # Enable or disable the site search
 search_enabled: true
 # Aux links for the upper right navigation

docs/api-docs.md

@@ -6,6 +6,9 @@ nav_order: 3
 
 # API Documentation
 
-The API documentation is generated independently of the rest of this docs and
+The API documentation is generated independently of the rest of these docs and
 can be found here:
-https://microbit-foundation.github.io/microbit-universal-hex/api/
+[https://microbit-foundation.github.io/microbit-universal-hex/api/](https://microbit-foundation.github.io/microbit-universal-hex/api/)
+
+The source code is well annotated with in-line documentation and
+[TypeDoc](http://typedoc.org) is used to generate the API documentation.

docs/index.md

@@ -10,16 +10,30 @@ nav_order: 1
 
 {: .fs-9 }
 
-<img alt="microbit-universal-hex logo" src="img/microbit-uh-logo.png" style="max-height: 125px; float: left; padding-right: 16px;">
+<img alt="microbit-universal-hex logo" src="img/microbit-uh-logo.png" style="max-height: 164px; float: left; padding-right: 16px;">
 
 Create Universal Hex files for the micro:bit.
 {: .fs-6 .fw-300 }
 
-[Quick Guide](quick-guide.html){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
-[View it on GitHub](https://github.com/microbit-foundation/microbit-universal-hex/){: .btn .fs-5 .mb-4 .mb-md-0 }
+[Quick Guide](quick-guide.html){: .btn .btn-primary .mb-4 .mb-md-0 .mr-2 }
+[API](api/){: .btn .btn-blue .mb-4 .mb-md-0 .mr-2 }
+[View it on GitHub](https://github.com/microbit-foundation/microbit-universal-hex/){: .btn .mb-4 .mb-md-0 }
 
 ---
 
-The documentation is currently a work in progress.
+This is the documentation for the micro:bit Universal Hex library.
 
-The menu on the left shows you the available documentation.
+The original hex files for the micro:bit were using the
+[Intel Hex format](https://en.wikipedia.org/wiki/Intel_HEX). With the micro:bit
+V2 release a new hex format was created to be able to flash any micro:bit
+version with a single file.
+
+The Universal Hex file format can contain the binary data for multiple micro:bit
+board versions and this TypeScript/JavaScript library can be used to create a
+micro:bit Universal Hex from two or more micro:bit Intel Hex files.
+
+## Navigation
+
+⬅️ The menu on the left shows you the available documentation pages.
+⬆️ The header at the top contains search bar
+⬇️ If you'd like to contribute to the docs there is an edit link at the footer

docs/uh-format.md

@@ -12,4 +12,4 @@ able to include data for multiple targets into a single file.
 
 This section of the docs is still a Work In Progress. For detailed information
 on the format please visit:
-https://github.com/microbit-foundation/spec-universal-hex
+[https://github.com/microbit-foundation/spec-universal-hex](https://github.com/microbit-foundation/spec-universal-hex)