2. 2
What Technical Writers Do
Bureau of Labor Statistics, U.S. Department of Labor, Occupational Outlook Handbook, 2014-15 Edition,
Technical Writers, on the Internet at http://www.bls.gov/ooh/media-and-communication/technical-
writers.htm (visited October 13, 2014).
3. 3
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
6. 6
What makes a task difficult to complete?
• Materials
• Time to complete
• Context switching
• Choices or paths through the task
• Multipurpose tools or many single-purpose tools
7. 7
Views of content
Content in a database Content as a database
“An object that can be
retrieved from its indexed
location, like locating a
dining room chair in an Ikea
warehouse.”
“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.”
Mark Baker, “The difference between content in a database and content as a
database”, spfe.info, Feb. 5, 2012
8. 8
Good documentation practices
Minimalism Task orientation
Usefulness
Usability
Structured authoring Semantic tagging
Modularity
Information architecture Consistency
Version control Release history
Topic ID management
9. 9
Instructions for Computer vs. Person
A list of instructions for a computer to do
Program Procedure
A list of instructions for a person to do
11. 11
Software Metrics
Lines of code Statements in a program
Complexity Paths through the program
Function points Functionality provided to the user
Coupling How independent modules are
Cohesion Internal relationships in a module
12. 12
Software to Documentation Metric Mapping
Software metric Documentation metric
Lines of code Steps/substeps
Complexity Choice points
Function points User-supplied parameters
Typed text
Coupling Branches
GUI screens/menus
Cohesion Notes/Cautions/Warnings/Dangers
Human factors Interface switches
Command-line interface commands
18. 18
Complexity measures over time (1)
0
20
40
60
80
100
120
2 2.1 2.5.3 2.6.2 2.6.4 3 3.1 3.5 4
Complexity
Version
Configuring the Controller VM
Cluster Software
Configuring the ESXi Host
Upgrading vSphere on a Host
(NX-1000/3050/6000 with 16
GB DOM)
Configuring HA and DRS in
vCenter
Configuring Host Networking
(ESXi)
Adding a Nutanix Node to
vCenter
Configuring SNMP
Installing the Controller VM
(ESXi)
Migrating a VM to Another
Cluster
20. 20
Quantifying improvement & prioritizing
While 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 … system design.
— Binny Gill, Director of Engineering, August 2012
<<Breath>>
Good morning everyone. My name is Ben Colborn. I am the manager of technical publications at Nutanix, a rapidly growing IT infrastructure company, going from 40 employees when I joined 3 years ago to almost 800. What I want to talk about today is a technique that we have developed to contribute to product usability enhancements with metrics calculated from the documentation, specifically DITA task topics. In other words, creating business intelligence from documentation.
Most discussions of the benefits of structured authoring, not surprisingly, focus around authoring and publishing, including localization and multichannel output. While these are tremendous benefits, today I want to suggest that there is another dimension: using structured documentation as commentary on the products that can feed into product improvement efforts.
Metrics are recorded by topic ID. Each record contains the title, path, release, and complexity score.
From here, the database is converted to CSV with XSLT so it can be imported in to Excel.
Weighting: no
Cutoff score: no
One final note before going into questions. Earlier I mentioned the QA plugin from ditanauts. You can access the blog I have with a couple former colleagues at ditanauts.org.