--- a/ObjectMemory.st	Wed Oct 04 21:32:06 2017 +0100
+++ b/ObjectMemory.st	Mon Oct 09 00:08:34 2017 +0100
@@ -3435,12 +3435,28 @@
 !
 
 newSpaceSize:newSize
-    "change the size of the newSpace. To do this, the current contents
-     of the newSpace may have to be tenured (if size is smaller).
-     Returns false, if it failed for any reason.
-     Experimental: this interface may valish without notice.
-
-     DANGER ALERT:
+    "
+    Change the size of the newSpace. Returns true if newspace 
+    has been resized, false otherwise. 
+
+    NOTE: 
+    Making newspace smaller forces objects in newspace to tenure. 
+    The tenuring may fail for various reasons, most notably: 
+
+      (i)  there's not enough old space to tenure objects to or
+      (ii) there are so many non-tenurable objects. 
+         
+    The former being most likely. Therefore, if shrinking newspace
+    fails, you may want to allocate more oldspace (#moreOldSpace:)
+    and try again, like:
+
+        (ObjectMemory newSpaceSize: desiredSize) ifFalse:[
+            (ObjectMemory moreOldSpace: ObjectMemory newSpaceSize) ifTrue:[
+                ObjectMemory newSpaceSize: desiredSize
+            ]
+        ].
+
+    WARNING
 	be careful too big of a size may lead to longer scavenge pauses.
 	Too small of a newSpace may lead to more CPU overhead, due to
 	excessive scavenges. You have been warned."