diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 9c7e7633e..8e51ab7de 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -13,14 +13,13 @@ package(s).
 
 Whenever Composer encounters a protected Composer repository it will try to authenticate
 using already defined credentials first. When none of those credentials apply it will prompt
-for credentials instead otherwise overridden and save those (or a token if Composer is able
-to retrieve one).
+for credentials and save them (or a token if Composer is able to retrieve one).
 
 |type|Generated by Prompt?|
 |---|---|
 |[http-basic](#http-basic)|yes|
 |[Inline http-basic](#inline-http-basic)|no|
-|[custom header](#custom-token-authentication)|no|
+|[Custom header](#custom-token-authentication)|no|
 |[gitlab-oauth](#gitlab-oauth)|yes|
 |[gitlab-token](#gitlab-token)|yes|
 
@@ -36,8 +35,8 @@ In this authentication storage method, an `auth.json` file will be present in th
 as the projects' `composer.json` file. You can either create and edit this file using the
 command line or manually edit or create it.
 
-> **Note: Make sure the `auth.json` file is in the `.gitignore`** otherwise
-> other people will be able to abuse your credentials.
+> **Note: Make sure the `auth.json` file is in `.gitignore`** to avoid
+> leaking credentials into your git history.
 
 ## Global authentication credentials
 
@@ -58,8 +57,9 @@ For all authentication methods it is possible to edit them using the command lin
 > **Note:** It is not recommended to manually edit your authentication options as this might
 > result in invalid json. Instead preferably use [the command line](#command-line-global-credential-editing).
 
-To manually edit it:
-```shell script
+To manually edit it, run:
+
+```sh
 composer config --global --editor [--auth]
 ```
 
@@ -74,7 +74,7 @@ Manually editing this file instead of using the command line may result in inval
 To fix this you need to open the file in an editor and fix the error. To find the location of
 your global `auth.json`, execute:
 
-```shell script
+```sh
 composer config --global --list
 ```
 
@@ -91,7 +91,7 @@ You can open this file in your favorite editor and fix the error.
 > your production server files.
 
 It is also possible to add credentials to a `composer.json` on a per-project basis in the `config`
-section or directly to the repository definition.
+section or directly in the repository definition.
 
 # Authentication methods
 
@@ -99,13 +99,13 @@ section or directly to the repository definition.
 
 ### Command line http-basic
 
-```shell script
+```sh
 composer config [--global] http-basic.example.org username password
 ```
 
 ### Manual http-basic
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```
 
@@ -128,13 +128,13 @@ in the same place where the Composer repository definition is defined.
 
 ### Command line inline http-basic
 
-```shell script
+```sh
 composer config [--global] repositories composer.unique-name https://username:password@repo.example.org
 ```
 
 ### Manual inline http-basic
 
-```shell script
+```sh
 composer config [--global] --editor
 ```
 
@@ -153,7 +153,7 @@ composer config [--global] --editor
 
 ### Manual custom token authentication
 
-```shell script
+```sh
 composer config [--global] --editor
 ```
 
@@ -178,17 +178,17 @@ composer config [--global] --editor
 ## gitlab-oauth
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> `gitlab-domains` section should also contain the url.
+> [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url.
 
 ### Command line gitlab-oauth
 
-```shell script
+```sh
 composer config [--global] gitlab-oauth.example.org token
 ```
 
 ### Manual gitlab-oauth
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```
 
@@ -203,17 +203,17 @@ composer config [--global] --editor --auth
 ## gitlab-token
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> `gitlab-domains` section should also contain the url.
+> [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url.
 
 ### Command line gitlab-token
 
-```shell script
+```sh
 composer config [--global] gitlab-token.example.org token
 ```
 
 ### Manual gitlab-token
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```