Merge pull request gocardless#4 from gocardless/blog-post-changes

Changes made while writing blog post

Author: maxmurdoch

README.md

@@ -1,16 +1,32 @@
 # Angular Style Guide
 
-## High Level Goals
+## Introduction
+
+This style guide addresses four areas: High-level Goals; Directory and File Structure; Parts of Angular; and General Patterns and Anti-patterns.
+
+High-level Goals are those that guide low-level decision making.
+
+Directory and File Structure addresses the way we organise our code and why.
+
+Parts of Angular addresses the core parts of AngularJS — routes, directives, controllers, modules, and templates.
+
+General Patterns and Anti-patterns addresses those that do not pertain to a specific part, but instead to the application at large.
+
+## Table of Contents
+1. [High-level Goals](#high-level-goals)
+2. [Directory and File Structure](#directory-and-file-structure)
+3. [Parts of Angular](#parts-of-angular)
+4. [General Patterns and Anti-patterns](#general-patterns-and-anti-patterns)
+
+## High-level Goals
 
 1. Prioritise readability.
 2. Be explicit, not implicit.
 3. Favour composability over inheritance.
 4. Think forward – ES6 and Web Components (Angular 2.0).
 5. Know [when to deviate](http://legacy.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds) from the style guide.
 
----
-
-## Directories & Files
+## Directory and File Structure
 
 ### Folder structure
 
@@ -74,13 +90,12 @@ Configures Providers. For example, `$locationProvider.html5Mode(true);`.
 
 ### Routes
 
-A view that points to a URL. Like components, each route contains all the HTML, CSS, JavaScript, and other dependencies needed to render itself.
+A view, made up of components and unique pieces of UI, that points to a URL. Like components, each route contains all the HTML, CSS, JavaScript, and other dependencies needed to render itself.
 
 ### Services
 
 Services contain Business logic. For example, `$http` abstractions.
 
----
 
 ## Parts of Angular
 
@@ -160,7 +175,6 @@ function nextPage() {
 }
 ```
 
----
 
 ### Directives
 
@@ -334,7 +348,6 @@ angular.module('AdminExpandComponentModule', [])
 - Don't rely on jQuery selectors. Use directives to target elements instead.
 - Don't use jQuery to generate templates or DOM. Use directive templates instead.
 
----
 
 ### Controllers
 
@@ -628,7 +641,6 @@ angular.module('AlertListComponentModule', [])
 
 - Don’t manipulate DOM in your controllers, this will make them harder to test. Use directives instead.
 
----
 
 ### Modules
 
@@ -697,7 +709,6 @@ import {AuthInterceptorModule} from '../services/auth-interceptor/auth-intercept
 import {OrganisationIdInterceptorModule} from '../services/organisation-id-interceptor/organisation-id-interceptor';
 ```
 
----
 
 ### Templates
 
@@ -718,7 +729,6 @@ _Why_: Avoids unnecessary expensive `$watch`ers.
 - Don’t use `ngInit` – use controllers instead.
 - Don’t use `<div ng-controller="Controller">` syntax. Use directives instead. 
 
----
 
 ## General Patterns and Anti-Patterns
 
@@ -795,7 +805,7 @@ angular.element(document).ready(function() {
 });
 ```
 
-### Anti-Patterns
+### Anti-patterns
 
 #### Don’t use the `$` name space in property names (e.g. `$scope.$isActive = true`).