diff --git a/docs/cli.md b/docs/cli.md
index a697ab7ae..21545da7a 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -51,7 +51,7 @@ One-off commands are started in new containers with the same config as a normal
 
 Links are also created between one-off commands and the other containers for that service so you can do stuff like this:
 
-    $ fig run db /bin/sh -c "psql -h \$DB_1_PORT_5432_TCP_ADDR -U docker"
+    $ fig run db psql -h db_1 -U postgres
 
 If you do not want linked containers to be started when running the one-off command, specify the `--no-deps` flag:
 
diff --git a/docs/env.md b/docs/env.md
index e6c383000..d9379bb42 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -6,6 +6,8 @@ title: Fig environment variables reference
 Environment variables reference
 ===============================
 
+**Note:** Environment variables are no longer the recommended method for connecting to linked services. Instead, you should use the link name (by default, <b><i>name</i>_1</b>) as the hostname to connect to. See the [fig.yml documentation](yml.html#links) for details.
+
 Fig uses [Docker links] to expose services' containers to one another. Each linked container injects a set of environment variables, each of which begins with the uppercase name of the container.
 
 To see what environment variables are available to a service, run `fig run SERVICE env`.
diff --git a/docs/wordpress.md b/docs/wordpress.md
index 701659255..c06eda676 100644
--- a/docs/wordpress.md
+++ b/docs/wordpress.md
@@ -44,7 +44,7 @@ Two supporting files are needed to get this working - first up, `wp-config.php`
 define('DB_NAME', 'wordpress');
 define('DB_USER', 'root');
 define('DB_PASSWORD', '');
-define('DB_HOST', getenv("DB_1_PORT_3306_TCP_ADDR") . ":" . getenv("DB_1_PORT_3306_TCP_PORT"));
+define('DB_HOST', "db_1:3306");
 define('DB_CHARSET', 'utf8');
 define('DB_COLLATE', '');
 
diff --git a/docs/yml.md b/docs/yml.md
index 060aaa05e..ea1dd4205 100644
--- a/docs/yml.md
+++ b/docs/yml.md
@@ -36,10 +36,10 @@ Override the default command.
 command: bundle exec thin -p 3000
 ```
 
+<a name="links"></a>
 ### links
 
-
-Link to containers in another service. Optionally specify an alternate name for the link, which will determine how environment variables are prefixed, e.g. `db` -> `DB_1_PORT`, `db:database` -> `DATABASE_1_PORT`
+Link to containers in another service. Optionally specify an alternate name for the link, which will determine how environment variables are prefixed, e.g. `db` -> `DB_1_PORT`, `db:database` -> `DATABASE_PORT`
 
 ```
 links:
@@ -48,6 +48,16 @@ links:
  - redis
 ```
 
+An entry with the alias' name will be created in `/etc/hosts` inside containers for this service, e.g:
+
+```
+172.17.2.186  db_1
+172.17.2.186  database
+172.17.2.187  redis_1
+```
+
+Environment variables will also be created - see the [environment variable reference](env.html) for details.
+
 ### ports
 
 Expose ports. Either specify both ports (`HOST:CONTAINER`), or just the container port (a random host port will be chosen).