diff --git a/misc-scripts/README.schema_patching b/misc-scripts/README.schema_patching
index 95cf0625c49455829ab35a6c693d38200d2887ee..232520a19ddbab6cd09a807525dccfa3900a3ab5 100644
--- a/misc-scripts/README.schema_patching
+++ b/misc-scripts/README.schema_patching
@@ -1,50 +1,99 @@
-Schema patching using patch_schema.pl
-=====================================
+*** Schema patching using patch_schema.pl ***
 
+This document describes the schema patch procedure for Ensembl core and
+variation databases.
 
-Schema patches are split into multiple files, each containing one
-"task". The convention for patch files (in ensembl/sql) is:
+
+-------------------------------------------------------------------------------
+Applying patches
+-------------------------------------------------------------------------------
+
+Schema patches are split into multiple files, each containing one "task". The
+convention for patch files (in ensembl/sql) is:
 
     patch_FROM_TO_[a-z].sql
 
-where FROM is the schema version before patching, TO the version to
-patch to, and [a-z] is a letter specifying the respective patch.
+where FROM is the schema version before patching, TO the version to patch to,
+and [a-z] is a letter specifying the respective patch.
+
+Each patch will put an entry into the meta table (meta_key = 'patch') to
+indicate that it has been applied successfully. this should make it easier to
+track which patches have been applied to which dbs.
 
-each patch will put an entry into the meta table (meta_key = 'patch') to
-indicate that it has been applied successfully. this should make it
-easier to track which patches have been applied to which dbs.
+This meta information is also used by the new script to determine which patches
+need to be applied to a db (note that you can still apply the patches manually
+if you prefer). The script is ensembl/misc-scripts/schema_patch.pl, run with
+--help to see all options it accepts (on the commandline or from an ini-style
+script passed in with --conffile).
 
-this meta information is also used by the new script to determine which
-patches need to be applied to a db (note that you can still apply the
-patches manually if you prefer). the script is
-ensembl/misc-scripts/schema_patch.pl, run with --help to see all options
-it accepts (on the commandline or from an ini-style script passed in
-with --conffile).
 
-Your usual procedure as a release coordinator would probably be:
+Typical use for core databases:
+-------------------------------
 
 1. check which patches need to be applied:
 
-this step is entirely optional, you can proceed to step (2) immediately
-if you like.
+This step is entirely optional, you can proceed to step (2) immediately if you
+like.
 
     $ ensembl/misc-scripts/schema_patch.pl --host ecs2 --port 3364 \
-        --user ensadmin --pass ensembl --pattern %_core_39_% --schema 39 \
+        --user xxx --pass xxx --pattern %_core_39_% --schema 39 \
         --dry_run 1 --interactive 0
 
 2. actually patch the databases:
 
     $ ensembl/misc-scripts/schema_patch.pl --host ecs2 --port 3364 \
-        --user ensadmin --pass ensembl --pattern %_core_39_% --schema 39 \
+        --user xxx --pass xxx --pattern %_core_39_% --schema 39 \
         --logfile /your/log/patch/schema_patch.39.log
 
-the script will run interactively and prompt you for each database
-matching the pattern. --logfile is optional but useful for keeping track
-of what you've done.
+The script will run interactively and prompt you for each database matching the
+pattern. --logfile is optional but useful for keeping track of what you've
+done.
+
+
+Patching variation databases:
+-----------------------------
 
-NOTE: the schema_patch.pl has been modified to work as well to patch variation
+The schema_patch.pl has been modified to work as well to patch variation
 databases. By default, and if you run it as above, it will patch the core
 databases. If you want to patch the variation_databases, the option
---patch_variation_database should be added, so it will read the ensembl-variation/sql
-directory and apply all the patch_*.sql to the database, as it does with the core
-databases
+--patch_variation_database should be added, so it will read the
+ensembl-variation/sql directory and apply all the patch_*.sql to the database,
+as it does with the core databases.
+
+
+-------------------------------------------------------------------------------
+Writing patches
+-------------------------------------------------------------------------------
+
+Each patch file *must* add an entry to the meta table to indicate that it has
+been run. This should be the last SQL statement in your patch, and look for
+example like this:
+
+# patch idenifier
+INSERT INTO meta (meta_key, meta_value) VALUES ('patch', 'patch_39_40_a.sql|rationalise_key_columns');
+
+
+The meta_value is the name of the patch file plus a short string describing the
+purpose of the patch, separated by a '|'.
+
+For each patch, the same line should be added to table.sql if it contains this
+patch. These entries get cleared from table.sql at the beginning of each
+release cycle.
+
+
+-------------------------------------------------------------------------------
+Related files
+-------------------------------------------------------------------------------
+
+The patch script:
+
+  ensembl/misc_scripts/patch_schema.pl
+
+Schema definition and patch files:
+
+  ensembl/sql/table.sql
+  ensembl/sql/patch*.sql
+
+  ensembl-variation/sql/table.sql
+  ensembl-variation/sql/patch*.sql
+