typos and bug fixes

devdocs/sketches/annotations.md

@@ -4,33 +4,33 @@ NOTE: Here, annotations are notes that are stored in a metrics system for
 review, not _Java Annotations_.
 
 The annotations support in nosqlbench is meant to allow for automatic
- grafanaAnnotation of important timestamps and qualifying details for a
+annotation of important timestamps and qualifying details for a nosqlbench
-  nosqlbench scenario.
+scenario.
 
 # Annotation Semantics
 
 Annotations are treated generally like events which mark a boundary
- between test scenario states in nosqlbench. Some annotations may be
+between test scenario states in nosqlbench.
- provided for a span of time, in which case the events are implied as
-  start and stop, or beginning and ending.
 
-Annotations always have at least one timestamp, and up to two
+Annotations always describe at least one instant in time, and possibly
-. Annotations with one timestamp mark an instant where an event
+two. When two instants are connected together with an annotation, then the
- is known to have occurred.
+annotation describes the lifetime that is bounded by two events:
+the beginning and the end. Annotations which describe an instant in time
+are tagged as "span: instant", and those which are connected with two
+different instants are tagged as "span: interval".
 
-When instrumenting an event for grafanaAnnotation, both positive and negative
+When instrumenting an event for annotation, both positive and negative
 outcomes must be instrumented. That is, if a user is expecting an
-  grafanaAnnotation marker for when an activity was started, they should
+annotation marker for when an activity was started, they should instead
-   instead see an error grafanaAnnotation if there indeed was an error. The
+see an error annotation if there indeed was an error. The successful
-    successful outcome of starting an activity is a different event
+outcome of starting an activity is a different event than the failure of
-     than the failure of it, but they both speak to the outcome of
+it, but they both speak to the outcome of trying to start an activity.
-      trying to start an activity.
 
 # NoSQLBench Annotation Level
 
 Each annotation comes from a particular level of execution with
- NoSQLBench. Starting from the top, each layer is nested within
+NoSQLBench. Starting from the top, each layer is nested within the last.
- the last. The conceptual view of this would appear as:
+The conceptual view of this would appear as:
 
               +--------+
               |   op   |
@@ -46,7 +46,6 @@ Each annotation comes from a particular level of execution with
     |               CLI ( Command Line Interface )    |
     +-------------------------------------------------+
 
-    
 That is, every op happens within a thread motor, every thread motor
 happens within an activity, and so on.
 
@@ -69,10 +68,8 @@ happens within an activity, and so on.
 - motor
   - thread.state - When a motor thread changes state
   - thread.error - When a motor thread throws an error
-- op
+- op -- There are no op-level events at this time
-  -- There are no op-level events at this time
+- application -- There are no application-level events at this time
-- application
-  -- There are no application-level events at this time
 
 ## tags
 
@@ -83,7 +80,6 @@ These standard tags should be added to every annotation emitted by
 **layer**: one of the core layers as above
 **event**: The name of the event within the layer as shown above
 
-
 type
 : <specific event name>
 layer