Adding Goal Lines and Target Areas to Charts

Overview

To track your team's release, performance or quarterly goals, annotate your report charts with goal or performance threshold lines, burn up guide lines, or target zones using a Dataplane Customizer Script.

The following Dataplane chart, for example, is a traditional Cumulative Flow Diagram of the status of project issues within the month of September. At the end of the four week reporting period, there's still substantial work that hasn't yet been started. As a project manager, sharing a PDF export of this report with management would require lots of written explanation to avoid an understandable barrage of concerned questions.

Using Dataplane chart annotations, though, we can provide concise, useful reference points so everyone shares a clear understanding of the unexpected delays.

Here we've added two goal lines and a box annotation to explain the large deviation in scope:

With Dataplane chart annotations we've clearly identified the original scope of work, can better gauge the amount of additional features requested in the early weeks, have noted the timing of the September 23 program management review, and called out the new work scope that resulted from that meeting.

Displaying goals and adjustments front-and-center on Dataplane charts and legends will help team members and management more easily visualize target metrics, understand course corrections and celebrate program and team success.

Chart Annotation Basics

In Dataplane you can annotate report charts with any number of styled lines or boxes. These chart annotations appear in the chart legend for easy reference and are visible everywhere the chart is displayed–within Dataplane, in exported PDF reports, in Jira dashboard gadgets and on Confluence pages.

The general syntax for a Customizer Script that adds line and box annotations to a report looks like this:

customizeChart {
	lineAnnotation "<name>" <property1> <value1> <property2> <value2> <property3> <value3>
	boxAnnotation "<name>" <property1> <value1> <property2> <value2> <property3> <value3>
}

By setting various properties of line and box annotations, you can easily control their position, color, size and labeling:

<value>

                
"<date>"

("<date or category>", <value>)

("<date or category>", <value>)

Adding Line Annotations

Chart line annotations are commonly used for:

• setting goal lines and thresholds
• creating burn down and burn up guide lines
• marking project milestones on the timeline

In Dataplane, line annotations can be added to the following chart types:

Chart Type		Line Annotation
Column chart
Normalized column chart
Bar chart
Normalized bar chart
Line chart
Area chart
Pie chart
Multi pie chart

The general notation for a Customizer Script line annotation is:

customizeChart {
	// just specify a value for a line across the whole chart
	lineAnnotation "<name>" at <value>
 
	// or, specify specific start and end points
	lineAnnotation "<name>" from ("<date or category>", <value>) to ("<date or category>", <value>)
} 

In addition, there are lots of shorthand options for drawing line annotations.  All of the following are valid ways of describing a line annotation:

customizeChart {
	lineAnnotation "Orig Velocity" from ("2013-05-01", 0) to ("2013-06-30", 100)
	lineAnnotation "Team Goal" at 100
	lineAnnotation "Internal SLA" from 75 to ("2013-08-01", 75) color "lightblue"	// initial SLA
	lineAnnotation "Internal SLA2" from ("2013-08-01", 100) to 100 color "blue"		// SLA revised August 1st
} 

Goal Lines and Thresholds

Goal lines and thresholds are usually represented by a line drawn parallel to the domain axis and across the entire width (or height) of the chart.  The most simple notation for this is:

customizeChart {
    lineAnnotation "Q1 Goal" at 120
}

Here "Q1 Goal" is the name that will be displayed in the chart legend, and 120 is the position on the range axis (in units of the range axis) at which the line will be drawn.

If we want to get more fancy we can style the line by applying color, width and pattern:

customizeChart {
    lineAnnotation "Q1 Goal" at 120 color "maroon" width 5 style "dashed"
    lineAnnotation "Q2 Goal" at 145 color "#5620D0" width 5 style "solid"		// use rgb color #5620D0 (purple)
    lineAnnotation "Q3 Goal" at 170 color (80,80,80) width 2 style "dotted"		// use rgb color #808080 (gray)
}

The following instructions create the exact same line annotations, but using the more abbreviated style keyword:

customizeChart {
    lineAnnotation "Q1 Goal" at 120 style ("dashed", "maroon", 5)
    lineAnnotation "Q2 Goal" at 145 style ("solid", "#5620D0", 5)		// use rgb color #5620D0 (purple)
    lineAnnotation "Q3 Goal" at 170 style ("dotted", "#808080", 2)		// use rgb color #808080 (gray)
}

And here's what the annotations look like:

For the Cumulative Flow Diagram chart in the example at the top of page, the following line annotations were used to mark the original scope of work and the adjusted scope of work:

customizeChart {
    lineAnnotation "M14 Original" at 120 color "orange" width 5 style "dotted"
    lineAnnotation "M14 Adjusted" at 168 color "red" width 2
}

Burn Down and Burn Up Guide Lines

Guide lines for classic burn down and burn up charts are typically drawn diagonally from start to end of the time period in order to show an ideal velocity of work.

The way to draw a Dataplane guide line is as follows:

customizeChart {
    lineAnnotation "Project Burn Up" from 0 to 100 color "blue" style "dotted"
}

If we anticipate a change in team velocity over the reporting period—for instance if additional resources are added to the project—we can even draw separate lines over partial periods to introduce more granularity in our ideal velocity:

customizeChart {
	lineAnnotation "Orig Velocity" from 0 to ("2013-08-10",30) color "blue" style "dashed"
	lineAnnotation "Orig Velocity +2" from ("2013-08-10",30) to 100 color "green" style "dashed"
} 

Marking Project Milestones

Line annotations are also a convenient way of marking key project milestones on your Dataplane report charts, such as:

customizeChart {
	lineAnnotation "Project Kickoff" at "2013-07-20" order 1 color "green"
	lineAnnotation "Added Blue Team" at "2013-08-08" order 2 color "blue"
	lineAnnotation "First PM Review" at "2013-09-23" order 3 color "orange"
	lineAnnotation "Q2 Division Status Update" at "2013-09-30" order 4 color "red"
} 

In this example, we've added the order property to each annotation so that they appear in the chart legend in a logical, date-based order.

Adding Box Annotations

Chart box annotations are commonly used for:

• identifying performance target zones
• highlighting areas to explain exceptional results

In Dataplane, box annotations can be added to the following chart types:

Chart Type		Box Annotation
Column chart (historical timeline charts)
Column chart (current value charts)
Normalized column chart (historical timeline charts)
Normalized column chart (current value charts)
Bar chart
Normalized bar chart
Line chart
Area chart
Pie chart
Multi pie chart

The general notation for a Customizer Script box annotation is:

customizeChart {
	boxAnnotation "<name>" from ("<date>", <value>) to ("<date>", <value>)
} 

Where the from property is always either of the left-most corners of the box and the to property is always the right-most, diagonal corner.

Target Zones and Highlighted Areas

For the Cumulative Flow Diagram chart in the example at the top of page, the following box annotation was used to provide an explanation for the large jump in scheduled work following a program management review:

customizeChart {
	// add a box highlight around September 23rd to highlight the PM review that day
    boxAnnotation "Sep 23 PM Review" from ("2013-09-23", 115) to ("2013-09-25",180) style ("dotted", "black", 2)
}

Putting it All Together

For completeness, here's the entire Dataplane report Customizer Script for the example report described at the top of the page:

customizeChart {
    series ANY color "gainsboro" order 50

    series "Work in Progress" color "green" order 1
    series "Open" color "blue" order 2
    series "Reopened" color "cyan" order 3
 
    lineAnnotation "M14 Adjusted" at 175 color "red" width 2
    lineAnnotation "M14 Original" at 120 color "orange" width 5 style "dotted"

    boxAnnotation "Sep 23 PM Review" from ("2013-09-23", 115) to ("2013-09-25",180) style ("dotted", "black", 2)
}

Which produces the following, nicely-annotated Jira Cumulative Flow Diagram report: