Improve documentation

* Capitalize in the beggining of a sentence
* Capitalize document filenames
* Add missing periods
* Add more markdown formatting where appropriate.
* Add links for URLs and references to documents in the repo
* Remove unnecessary indentation
* Wrap at 80 characters

No changes in the instructions or wording were done is this commit.

4 files changed, 26 insertions, 32 deletions

diff --git a/docs/archaeology.md b/docs/Archaeology.md
index 3aac8b1..37a363b 100644
--- a/docs/archaeology.md
+++ b/docs/Archaeology.md
@@ -1,7 +1,7 @@
 ## Archaeology
 
-One of the stated aims of Baserock has been to ensure that old systems can
-be reproduced a long time into the future (decades, for example).
+One of the stated aims of Baserock has been to ensure that old systems can be
+reproduced a long time into the future (decades, for example).
 
 Stating it doesn't make it true, though.
 
@@ -12,7 +12,9 @@ themselves; we had never specified the definitions format, after all. In the
 end it seemed more productive to fix the assumptions and move forward, rather
 than make ybd repeat the mistakes.
 
-For what it's worth, as of 2016-04-10 ybd parses all the way back to baserock-14.40, which was the first tag where the morph files were organised into subdirectories. Going back further could be attempted, if we consider it
+For what it's worth, as of 2016-04-10 ybd parses all the way back to
+baserock-14.40, which was the first tag where the morph files were organised
+into subdirectories. Going back further could be attempted, if we consider it
 worthwhile to exhume the builds further back.
 
 This is how ybd behaves on various historical versions of ci.morph:
@@ -30,4 +32,4 @@ baserock-15.17-rc:
     (VERSION: 1) crashes on pygobject
 
 baserock-15.19:
-    (VERSION: 3) builds successfully
\ No newline at end of file
+    (VERSION: 3) builds successfully
diff --git a/docs/dependencies.md b/docs/Dependencies.md
index 9001b00..134b91c 100644
--- a/docs/dependencies.md
+++ b/docs/Dependencies.md
@@ -1,12 +1,13 @@
-## dependencies
+## Dependencies
 
-ybd requires git, gcc, make, autotools, python, tar, wget. note that the Baserock definitions also require gawk.
+ybd requires git, gcc, make, autotools, python, tar, wget. Note that the
+Baserock definitions also require gawk.
 
-so for a Debian-based system:
+So for a Debian-based system:
 
     apt-get update; apt-get install build-essential gawk git m4
 
-...and a Fedora-based system:
+… and a Fedora-based system:
 
     yum install make automake gcc gcc-c++ kernel-devel git gawk m4
 
@@ -16,23 +17,19 @@ ybd also depends on [pyfilesystem](http://pyfilesystem.org),
 [requests](https://github.com/kennethreitz/requests),
 and optionally [jsonschema](https://github.com/Julian/jsonschema).
 
-to serve artifacts using kbas, it additionally requires
+To serve artifacts using kbas, it additionally requires
 [bottle](https://github.com/bottlepy/bottle) and optionally
-[cherrypy](https://github.com/cherrypy/cherrypy.git)
+[cherrypy](https://github.com/cherrypy/cherrypy.git).
 
-to use the Riemann functionality, it additionally requires
-[riemann-client](https://github.com/borntyping/python-riemann-client)
+To use the Riemann functionality, it additionally requires
+[riemann-client](https://github.com/borntyping/python-riemann-client).
 
-if you trust the Python Package Index (PyPI) and pip is available on your
+If you trust the Python Package Index (PyPI) and pip is available on your
 machine, you can install these dependencies with:
 
-```
     pip install fs pyyaml sandboxlib requests jsonschema bottle cherrypy riemann-client
-```
 
 If you need to install pip itself:
 
-```
     wget https://bootstrap.pypa.io/get-pip.py
     python get-pip.py
-```
diff --git a/docs/testing.md b/docs/Testing.md
index f78337c..dc431a5 100644
--- a/docs/testing.md
+++ b/docs/Testing.md
@@ -1,13 +1,15 @@
 check_parsing
 -------------
-YBD aims to normalise definitions into a more understandable representation.
-With the addition of 'parse-only' mode, ybd can dump this representation as
+
+ybd aims to normalise definitions into a more understandable representation.
+With the addition of _parse-only_ mode, ybd can dump this representation as
 json, and we can confirm there is no unexpected data.
 
 FIXME: identify at least one valid test-case here.
 
 check_cache_keys
 ----------------
+
 Since ybd 15.44, the cache-key algorithm appears stable and can be
 applied to definitions as far back as baserock-14.40.
 
@@ -16,7 +18,6 @@ algorithm. This doesn't matter much for the cache-key algorithm itself,
 since it is versioned, but checking that we can get to these values also
 confirms that we can still parse the old definitions files themselves.
 
-```
     baserock-14.40
     0: ci.6788f6634d42f0a42682bd2208cb123f69a157b4a50ac40108d91029558ec623
     1: ci.b9de86669ce182e60e3f9445e6394b478b67a2c73b4c0764491c158c5f2569e9
@@ -28,10 +29,10 @@ confirms that we can still parse the old definitions files themselves.
     baserock-15.47.1
     0: ci.a809e39d26fea31b2dc674e190f6367a10cedaffe644775a59a93719cc5d5290
     1: ci.ce7f81b2e294c1893a08e4b18cf1d9a74f5e49bb58f7099ab55f656a05d887b4
-```
 
 check splits
 ------------
+
 We reduce the size of systems artifacts by installing a only subset of the
 outputs from the builds during the assembly process. The code for this
 is mainly in splitting.py, and involves applying regex expressions to the
@@ -44,9 +45,8 @@ list of generated files, and compare new runs against it as a regression test.
 
 The best candidate is minimal-system, since this expressly makes use of a lot
 of splitting. The proposed test case is from Richard Dale's original commit
-of the split functionality...
+of the split functionality…
 
-```
     artifact-version: omitted
     definitions version: baserock-15.47.1
     ybd version: rdale/150-master-splitting
@@ -57,11 +57,9 @@ of the split functionality...
       result: 6c3c9ad75990b93e1927012928444b83
     find . -type f | sort | wc -l
       result: 155
-```
 
-But we should also test (say) devel-system...
+But we should also test (say) devel-system…
 
-```
     artifact-version: omitted
     definitions version: baserock-15.47.1
     ybd version: rdale/150-master-splitting
@@ -75,6 +73,4 @@ But we should also test (say) devel-system...
     find . -type f | sort | md5sum
       result: 5c6e4561557d319059986c161565f4bf
 
-```
-
-The above was achieved on AWS
\ No newline at end of file
+The above was achieved on AWS.
diff --git a/docs/releasing.md b/docs/releasing.md
index 6c553b3..ab39365 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -1,10 +1,10 @@
 # Releasing
 
-This summarises what 'releasing' means for ybd - it's a work-in-progress. 
+This summarises what _releasing_ means for ybd - it's a work-in-progress.
 
 ### Past
 
-In the first months there were no 'releases' of ybd. The early goals of the
+In the first months there were no releases of ybd. The early goals of the
 project were to parse definitions as fast as possible, then build them, then
 deploy them.
 
@@ -65,4 +65,3 @@ server time, because actual system builds are big and heavy. To improve on
 this we'd benefit from establishing a reference definition set which is
 specifically for exercising ybd/definitions/spec.
 
-