diff --git a/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java b/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
index 69251b70b7..853363645c 100644
--- a/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
+++ b/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
@@ -162,8 +162,10 @@ public interface TemplateBuilder {
    Template build();
 
    /**
-    * options such as inbound ports and run scripts.
+    * Sets options on the template (i.e. items which adorn a created node rather than restricting selection of the node).
+    * Note that this method typically replaces any options previously specified in the builder.
+    * Normal usage is to build up all options and pass them to the builder with a single call to this method.
     */
    TemplateBuilder options(TemplateOptions options);
 
-}
\ No newline at end of file
+}
diff --git a/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java b/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
index 1902dfa441..fc4f91837a 100644
--- a/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
+++ b/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
@@ -43,7 +43,7 @@ import com.google.common.collect.Maps;
  * operation. <h2>
  * Usage</h2> The recommended way to instantiate a TemplateOptions object is to
  * statically import TemplateOptions.* and invoke a static creation method
- * followed by an instance mutator (if needed):
+ * followed by any/all desired instance mutators.
  * <p/>
  * <code>
  * import static org.jclouds.compute.options.TemplateOptions.Builder.*;
@@ -52,6 +52,11 @@ import com.google.common.collect.Maps;
  * templateBuilder.options(inboundPorts(22, 80, 8080, 443));
  * Set<? extends NodeMetadata> set = client.createNodesInGroup(tag, 2, templateBuilder.build());
  * <code>
+ * <p/>
+ * Note that options can only be assigned to a builder once, so if assigning e.g. inboundPorts and tags,
+ * that must be done in with mutators in a single call to options --
+ * <code>templateBuilder.options(inboundPorts(22, 80, 8080, 443).tags("I love it!"))</code>
+ * -- not as repeated calls to <code>options</code>.
  * 
  * @author Adrian Cole
  */