Improving product usability with task complexity metrics

Ben ColbornTraining & Documentation

Nutanix, Inc.

Good documentation practices

FOUNDATION

Minimalism Task orientationUsefulnessUsability

Structured authoring Semantic taggingModularity

Information architecture

Consistency

Version control Release historyTopic ID management

ProgramA list of instructions for a computer to do

ProcedureA list of instructions for a person to do

FOUNDATION

Request from engineering

It would be nice for the doc team to have a metric for complexity of procedures. … That will bring objectivity to the whole topic and we can track progress as well.

— Binny Gill, Director of Engineering, April 2012

INSPIRATION

Content as a databaseContent in a database“An object that can be retrieved from its indexed location, like locating a dining room chair in an Ikea warehouse.”

Content as a database“A record that can be examined and presented from different angles based on different properties, which can be selected based on any of these properties, and which can be related to other records based on common properties.”

INSPIRATION

Mark Baker, “The difference between content in a database and content as a database”, spfe.info, Feb. 5, 2012

Software MetricsINSPIRATION

Lines of code Statements in a programComplexity Paths through the programFunction points Functionality provided to the

userCoupling How independent modules

areCohesion Internal relationships in a

module

MAPPING

Software metric

Documentation metric

Lines of code Steps/substeps

Complexity Choice points

Function points User-supplied parametersTyped text

Coupling BranchesGUI screens/menus

Cohesion Notes/Cautions/Warnings/Dangers

Human factors Interface switchesCommand-line interface commands

MAPPINGDocumentation metric

XPath expression

Steps //step[not(substeps)] | //substepChoice points //choices | //choicetable | //step[contains(text(), "If")]Branches //step//xrefnCLI commands //step//codeblock[starts-with(text(), "ncli")]root commands //step//codeblock[starts-with(text(), "#")] |

//step//codeblock[contains(text(), "sudo")]

Non-root commands //step//codeblock[starts-with(text(), "$")]GUI screens/menus //uicontrolInterface switches //*[contains(text(), "vSphere client")] |

//*[contains(text(), "ssh")] | //*[contains(text(), "web console")] |

Notes/Cautions/Warnings/Dangers

//note[not(@type)] | //note[@type="caution"] | //note[@type="warning"] | //note[@type="important"] |//note[@type="danger"]

User-supplied parameters

//varname

Typed text //userinput

Complexity measures over timeRESULT

Genesi

s

Bayo

u-2.5.

3

Bayou

-2.5.0

Amazo

n-FP1

Amazo

n-PS2

0.0

20.0

40.0

60.0

80.0

100.0

120.0

Average To Upgrade the Nutanix Cluster from Version 2.1To Create a Nutanix Cluster in vCenter To Configure a Cluster with Multiple BlocksTo Upgrade the Nutanix Cluster from the Customer Preview Release

To Configure the Cluster

To Configure the Controller VM To Configure the Nutanix vCenter IP AddressTo Complete Replacing a Fusion-io Drive To Add a Node to a ClusterTo Upgrade the Nutanix Cluster to Version 2.0 FP1 To Complete Replacing a Hard Disk DriveTo Configure the Controller VM IP Address To Configure a Host IP AddressTo Redeploy the Controller VMs To Create the DatastoreTo Create a VMFS Datastore To Shut Down a Nutanix ClusterTo Add CPU-Test To Create a RDM-Based Virtual Machine

Quantifying improvement & prioritizingWhile the engineers are focused on their individual sub-areas, the complexity of the overall workflows is not always clear to them. Using these metrics has converted a subjective and often contentious topic into an objective topic which now encourages more constructive discussions in my team. It also helps me demonstrate to upper management and stakeholders the improvements being made in an otherwise fuzzy and often overlooked aspect of system design.

— Binny Gill, Director of Engineering, August 2012

RESULT