diff --git a/doc/articles/http-basic-authentication.md b/doc/articles/http-basic-authentication.md
index c3d09fc34..af62fe2df 100644
--- a/doc/articles/http-basic-authentication.md
+++ b/doc/articles/http-basic-authentication.md
@@ -1,51 +1,59 @@
 <!--
-    tagline: How to use http basic authentication
+    tagline: Access privately hosted packages
 -->
 
-# Http basic authentication
+# HTTP basic authentication
 
-Your [satis](handling-private-packages-with-satis.md) server could be
-secured with http basic authentication. In order to allow your project
+Your [Satis or Toran Proxy](handling-private-packages-with-satis.md) server
+could be secured with http basic authentication. In order to allow your project
 to have access to these packages you will have to tell composer how to
 authenticate with your credentials.
 
-The most simple way to provide your credentials is providing your set
+The simplest way to provide your credentials is providing your set
 of credentials inline with the repository specification such as:
 
-    {
-        "repositories": [
-            {
-                "type": "composer",
-                "url": "http://extremely:secret@repo.example.org"
-            }
-        ]
-    }
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "http://extremely:secret@repo.example.org"
+        }
+    ]
+}
+```
 
 This will basically teach composer how to authenticate automatically
 when reading packages from the provided composer repository.
 
 This does not work for everybody especially when you don't want to
 hard code your credentials into your composer.json. There is a second
-way to provide these details and is via interaction. If you don't
+way to provide these details and it is via interaction. If you don't
 provide the authentication credentials composer will prompt you upon
 connection to enter the username and password.
 
-There is yet another way to provide these details and is via a file
-`auth.json` inside your `COMPOSER_HOME` which looks something like
-`/Users/username/.composer/auth.json`
-
-    {
-        "basic-auth": [
-            "repo.example1.org": {
-                "username": "my-username1",
-                "password": "my-secret-password1"
-            },
-            "repo.example2.org": {
-                "username": "my-username2",
-                "password": "my-secret-password2"
-            }
-        ]
-    }
-
-This then will provide http basic authentication for two domains
-serving packages with two different sets of credentials.
+The third way if you want to pre-configure it is via an `auth.json` file
+located in your `COMPOSER_HOME` or besides your `composer.json`.
+
+The file should contain a set of hostnames followed each with their own
+username/password pairs, for example:
+
+```json
+{
+    "basic-auth": [
+        "repo.example1.org": {
+            "username": "my-username1",
+            "password": "my-secret-password1"
+        },
+        "repo.example2.org": {
+            "username": "my-username2",
+            "password": "my-secret-password2"
+        }
+    ]
+}
+```
+
+The main advantage of the auth.json file is that it can be gitignored so
+that every developer in your team can place their own credentials in there,
+which makes revokation of credentials much easier than if you all share the
+same.