Improve the readme file

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
+

_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.