diff --git a/README.md b/README.md
index 7960866..be8a2f7 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,32 @@
-This is the repository for the website at http://signalk.github.io
+# SignalK.org
 
-#### Instructions for adding posts, pages, etc.
+This is the repository for the [Signal K](http://signalk.org) website.
 
-New blog posts go in the _posts folder and should be named YYYY-MM-DD-post-name.<filetype>. The front matter for these
-posts should include a title and author. The layout should be 'post'. Markdown, textile and HTML are pretty much the
-format choices. Markdown is preferred except in cases where the content is to complex.
+## Making Changes
 
-Pages that aren't API reference material should be in the root folder, API reference pages go in the api folder. These
-don't need a date prepended and their layout should be 'page'.
+The website is hosted by GitHub Pages and most content is authored in Markdown format. HTML is also acceptable. Each
+page has at the beginning a section called _front matter_. This is YAML between three dashes and looks like:
 
-New navbar links can be addd in _includes/header.html and use Bootstrap classes for styling.
+```
+---
+layout: page
+title: Some Page
+---
+```
+
+Every page needs at least a layout and a title. It is also useful to add a description to be helpful to search engines.
+Valid layouts can be found in the `_layouts` directory. Generally, you will want to use `onecolumn`, but `post` and
+`rsidebar` can also be used. If you specify `rsidebar`, you will also need to create content for the sidebar and a
+front matter variable `sidebar` which points to the sidebar file. This file should be placed in the `_includes`
+directory. See `installation.md` or `overview.md` for an example of how this works.
+
+To create a new published subdirectory, add it to `collections` in `_config.yml`. Published subdirectories should be
+named with a leading underscore.
+
+If you rename a page or move its content elsewhere, be a good web citizen and add a redirect from the old location to
+the new. For instance, if you want to move the content of `overview.md` to `getting_started.md`, don't just remove
+`overview.md`, rather remove its content and add a `redirect` variable to its front matter pointing to the new page. See
+`specification.md` for an example of this.
+
+When creating links to local resources, such as between pages, prefix them with `{{site.path}}` and use absolute, rather
+than relative paths. This ensures links continue to work in staging.
diff --git a/specification.md b/specification.md
index 11a930b..4a10581 100644
--- a/specification.md
+++ b/specification.md
@@ -9,4 +9,4 @@ redirect: http://signalk.org/specification/master/keys
 ## {{page.title}}
 
 The specification has been relocated to the consolidated Signal K documentation at
-{{site.baseurl}}/specification/master. You should be redirected shortly.
+{{site.path}}/specification/master. You should be redirected shortly.