diff --git a/basis/compiler/tree/escape-analysis/allocations/allocations-docs.factor b/basis/compiler/tree/escape-analysis/allocations/allocations-docs.factor
new file mode 100644
index 0000000000..eb9bf84808
--- /dev/null
+++ b/basis/compiler/tree/escape-analysis/allocations/allocations-docs.factor
@@ -0,0 +1,28 @@
+USING: compiler.tree disjoint-sets help.markup help.syntax ;
+IN: compiler.tree.escape-analysis.allocations
+
+HELP: allocations
+{ $var-description "A map from values to one of the following:"
+  { $list
+    "f -- initial status, assigned to values we have not seen yet; may potentially become an allocation later"
+    "a sequence of values -- potentially unboxed tuple allocations"
+    "t -- not allocated in this procedure, can never be unboxed"
+  }
+} ;
+
+HELP: compute-escaping-allocations
+{ $description "Compute which tuples escape" } ;
+
+HELP: escaping-values
+{ $var-description "We track escaping values with a " { $link disjoint-set } "." } ;
+
+HELP: slot-access
+{ $var-description "We track slot access to connect constructor inputs with accessor outputs." } ;
+
+HELP: value-classes
+{ $var-description "A map from values to classes. Only for " { $link #introduce } " outputs." } ;
+
+ARTICLE: "compiler.tree.escape-analysis.allocations" "Tracking memory allocations"
+"Tracks memory allocations and unboxes those which can be determined never escapes." ;
+
+ABOUT: "compiler.tree.escape-analysis.allocations"
diff --git a/basis/compiler/tree/escape-analysis/allocations/allocations.factor b/basis/compiler/tree/escape-analysis/allocations/allocations.factor
index 1f8634efa9..85e1f42a9b 100644
--- a/basis/compiler/tree/escape-analysis/allocations/allocations.factor
+++ b/basis/compiler/tree/escape-analysis/allocations/allocations.factor
@@ -5,18 +5,12 @@ namespaces sequences stack-checker.values ;
 FROM: namespaces => set ;
 IN: compiler.tree.escape-analysis.allocations
 
-! A map from values to classes. Only for #introduce outputs
 SYMBOL: value-classes
 
 : value-class ( value -- class ) value-classes get at ;
 
 : set-value-class ( class value -- ) value-classes get set-at ;
 
-! A map from values to one of the following:
-! - f -- initial status, assigned to values we have not seen yet;
-!        may potentially become an allocation later
-! - a sequence of values -- potentially unboxed tuple allocations
-! - t -- not allocated in this procedure, can never be unboxed
 SYMBOL: allocations
 
 : (allocation) ( -- allocations )
@@ -31,8 +25,6 @@ SYMBOL: allocations
 : record-allocations ( allocations values -- )
     (allocation) '[ _ set-at ] 2each ;
 
-! We track slot access to connect constructor inputs with
-! accessor outputs.
 SYMBOL: slot-accesses
 
 TUPLE: slot-access slot# value ;
@@ -42,7 +34,6 @@ C: <slot-access> slot-access
 : record-slot-access ( out slot# in -- )
     <slot-access> swap slot-accesses get set-at ;
 
-! We track escaping values with a disjoint set.
 SYMBOL: escaping-values
 
 SYMBOL: +escaping+
@@ -126,7 +117,6 @@ DEFER: copy-value
         [ nth swap copy-value ]
     } cond ;
 
-! Compute which tuples escape
 SYMBOL: escaping-allocations
 
 : compute-escaping-allocations ( -- )