From 5c595146a0f055db281ab5f8071b0d00314f48d5 Mon Sep 17 00:00:00 2001
From: Simon Erkelens <github@casa-laguna.net>
Date: Thu, 19 Dec 2013 20:37:52 +0100
Subject: [PATCH] MINOR Documentation slightly improved for js inclusion

Although I'm not the best documentor.
---
 docs/en/reference/requirements.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/en/reference/requirements.md b/docs/en/reference/requirements.md
index f6a6fa61e..5bd406545 100644
--- a/docs/en/reference/requirements.md
+++ b/docs/en/reference/requirements.md
@@ -139,11 +139,15 @@ to change inclusion-order, other than using *Requirements::clear* and rebuilding
 requirements. Caution: Inclusion order is both relevant for CSS and Javascript files in terms of dependencies,
 inheritance and overlays - please be careful when messing with the order of Requirements.
 
-NOTE:
-By default, SilverStripe includes all Javascript files at the bottom of the page body. If this causes problems for you,
+### Javascript placement
+
+By default, SilverStripe includes all Javascript files at the bottom of the page body, unless there's another script already loaded, then, it's prepended to the first `<script>` tag. If this causes problems for you,
 for example if you're using animation that ends up showing everything until the bottom of the page loads, or shows
-buttons before pushing them will actually work, you can change this behaviour through
-the `Requirements.write_js_to_body` configuration setting.
+buttons before pushing them will actually work, you can change this behaviour though.
+
+With the `Requirements.write_js_to_body`, you can configure if the javascripts are written to the head (false) or body (true).
+
+With the `Requirements.force_js_to_bottom`, you can enforce Silverstripe to write the javascript to the bottom of the page body, despite there being an earlier script tag. For example, when you have asynchronous scripts for Twitter earlier in your body (and stop speedtests from explaining about "scripts above the fold")
 
 ## CMS Requirements