expand the readme markdown files

Bug: 28530837
Test: looked at the markdown in gitiles

Change-Id: Ie4624d47a466f5d67a1f9dffa86ff3ef8b9929a0

5 files changed, 52 insertions, 29 deletions

diff --git a/README b/README
deleted file mode 100644
index 1cde34e..0000000
--- a/README
+++ /dev/null
@@ -1,5 +0,0 @@
-VERSION
--------
-This file should be the source of truth of the version number for a checkout.
-
-It will be updated by Builders and used by tools needing version information.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a320e92
--- /dev/null
+++ b/README.md
@@ -0,0 +1,12 @@
+# The Brillo Developer Kit (BDK)
+
+This is the bdk which is used to build Brillo.
+
+# Directory Listing
+
+* [cli/](/cli/): The main body of code that makes up the `bdk` tool.
+* [schema/](/schema/): Specification for the user's project.xml files.
+* [CHANGES](/CHANGES.md): A log highlighting major features across releases.
+* [VERSION](/VERSION): This file should be the source of truth of the version
+  number for a checkout.  It will be updated by Builders and used by tools
+  needing version information.
diff --git a/cli/README.md b/cli/README.md
index 49c08d8..25447c4 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -1,3 +1,4 @@
-Bdk CLI for Brillo development
+# The Brillo Developer Kit (BDK) command line interface (CLI)
 
-Bdk is a CLI tool to manage Brillo product development
+This holds all the code (written in Python) for the `bdk` tool: a CLI tool to
+manage Brillo product development.
diff --git a/schema/README.md b/schema/README.md
index a07cecd..77288c5 100644
--- a/schema/README.md
+++ b/schema/README.md
@@ -1,5 +1,4 @@
-Brillo Developer Kit Schemas
-============================
+# Brillo Developer Kit Schemas
 
 The Brillo Developer Kit provides a number of configuration files for
 use by the end developer.  Those files are expressed in XML and the
@@ -12,14 +11,44 @@ exploring other problems.
 
 The current supported schemas are as follows:
 
-  * bdk.rng: Specifies how to assemble device and developer software
-             for defined Brillo devices from packs and targets.
-  * packs.rng: Specifies a collection of resources and how they map
-               into a device.
-  * targets.rng: Specifies a target device and what tree of packs make
-                 up its software.
+  * [bdk.rng](/schema/bdk.rng): Specifies how to assemble device and developer
+    software for defined Brillo devices from packs and targets.
+  * [packs.rng](/schema/packs.rng): Specifies a collection of resources and how
+    they map into a device.
+  * [targets.rng](/schema/targets.rng): Specifies a target device and what tree
+    of packs make up its software.
 
+# Format
+
+The schema files are written in [RELAX NG](http://relaxng.org/).
+
+# Testing
 
 When updating the schemas with "breaking" changes, a new version should be
 added to the version list for all root nodes (bdk-config, packs, targets) and
 the prior version frozen and archived under "versions/<version_number>".
+
+## Quick Tests
+
+Quick validation can be performed with the xmllint tool:
+
+```sh
+$ xmllint file.xml - -relaxng bdk.rng
+```
+
+Or with better output:
+
+```sh
+$ jing bdk.rng file.xml
+```
+
+Or in python with:
+
+```python
+from lxml import etree
+rng_doc = etree.parse('bdk.rng')
+rng = etree.RelaxNG(rng_doc)
+doc = etree.parse('file.xml')
+print rng.validate(doc) # => False
+print rng.error_log # => Errors
+```
diff --git a/schema/bdk.rng b/schema/bdk.rng
index 3623e21..89faeeb 100644
--- a/schema/bdk.rng
+++ b/schema/bdk.rng
@@ -15,20 +15,6 @@
       limitations under the License.
 
       Project specification schema for the Brillo Developer Kit.
-
-      Quick validation can be performed with the xmllint tool:
-        xmllint file.xml - -relaxng bdk.rng
-
-      Or with better output:
-        jing bdk.rng file.xml
-
-      Or in python with:
-        from lxml import etree
-        rng_doc = etree.parse('bdk.rng')
-        rng = etree.RelaxNG(rng_doc)
-        doc = etree.parse('test.xml')
-        print rng.validate(doc) # => False
-        print rng.error_log # => Errors
   -->
 <grammar xmlns="http://relaxng.org/ns/structure/1.0"
          datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">