From 784f7b31394f2ec8f00aaf99dd0e06bbd807df04 Mon Sep 17 00:00:00 2001
From: Simon Holywell <simon@emosaic.co.uk>
Date: Mon, 13 Jul 2015 12:54:36 +0100
Subject: [PATCH] Improve the readme file

---
 README.md                   | 25 +++++++++++++++++++++++--
 _includes/sqlstyle.guide.md |  2 +-
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 3d6effc..215b89e 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,31 @@
 # SQL style guide
 
-**[Read it](http://www.sqlstyle.guide)**
+**[Read the guide](http://www.sqlstyle.guide)**
+
 ---
 
+## General
+
+The guide is written in [Markdown][md-lang] and uses [Jekyll][jekyll] via
+[GitHub's Pages][gh-pages] facility to render itself upon pushing to the `gh-pages`
+branch.
+
+## Sources
+
+The markdown source for the guide can be found in [_includes/sqlstyle.guide.md][md]
+
 ## Installing for local development
 
-There is a Gemfile supplied so you just need to follow https://help.github.com/articles/using-jekyll-with-pages/#installing-jekyll
+There is a Gemfile supplied so you just need to follow the
+[GitHub Pages documentation][gh-pages-help] to install the dependencies.
 
 To then run it locally `bundle exec jekyll serve`
+
+
+
+[md-lang]: http://daringfireball.net/projects/markdown/
+[jekyll]: http://jekyllrb.com/
+[gh-pages]: https://pages.github.com/
+[md]: https://github.com/treffynnon/sqlstyle.guide/blob/gh-pages/_includes/sqlstyle.guide.md
+[gh-pages-help]: https://help.github.com/articles/using-jekyll-with-pages/#installing-jekyll
+
diff --git a/_includes/sqlstyle.guide.md b/_includes/sqlstyle.guide.md
index 1c2f36a..996b453 100644
--- a/_includes/sqlstyle.guide.md
+++ b/_includes/sqlstyle.guide.md
@@ -95,7 +95,7 @@ SELECT first_name
 ### Columns
 
 * Always use the singular name.
-* Avoid simply using `id` as the primary identifier for the table.
+* Where possible avoid simply using `id` as the primary identifier for the table.
 * Do not add a column with the same name as its table and vice versa.
 * Always use lowercase except where it may make sense not to such as proper nouns.