Document the augment declarator

Author: moritz

lib/Language/variables.pod

@@ -445,7 +445,22 @@ but still aren't installed in a scope:
 
 =head2 The C<augment> Declarator
 
-=comment TODO
+With C<augment>, you can add attributes and methods to existing classes and
+grammars, provided you activated the C<MONKEY-TYPING> pragma first.
+
+Since classes are usually C<our> scoped, and thus global, this means modifying
+global state, which is strongly discouraged. For almost all situations, there
+are better soluations.
+
+    # don't do this
+    use MONKEY-TYPING;
+    augment class Int {
+        method is-answer { self == 42 }
+    }
+    say 42.is-answer;       # True
+
+(In this case, the better solution would be to use a
+L<function|/language/functions>).
 
 =head2 The C<supersede> Declarator