![13
Metric to XPath Mapping (1)
Documentation metric XPath expression
Steps step[not(substeps)]
substep
Choice points choices
choicetable
step[contains(text(), "If")]
Branches step//xref
nCLI 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(), "$")]](https://image.slidesharecdn.com/idwtaskcomplexitymetrics-151204191147-lva1-app6892/85/Improving-product-usability-with-task-complexity-metrics-13-320.jpg)
![14
Metric to XPath Mapping (2)
Documentation metric XPath expression
GUI screens/menus uicontrol
wintitle
Interface 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](https://image.slidesharecdn.com/idwtaskcomplexitymetrics-151204191147-lva1-app6892/85/Improving-product-usability-with-task-complexity-metrics-14-320.jpg)
Improving product usability with task complexity metrics
- 1. Improving product usability with task complexity metrics Ben Colborn Technical Publications, Nutanix, Inc.
- 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
- 5. Foundations
- 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
- 10. Mapping
- 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
- 13. 13 Metric to XPath Mapping (1) Documentation metric XPath expression Steps step[not(substeps)] substep Choice points choices choicetable step[contains(text(), "If")] Branches step//xref nCLI 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(), "$")]
- 14. 14 Metric to XPath Mapping (2) Documentation metric XPath expression GUI screens/menus uicontrol wintitle Interface 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
- 15. 15 Implementation Script (PowerShell, Python) 1. Declare Xpath expressions 2. Open each file in the repository 3. Count occurences of each expression and sum 4. Write to log file Open Toolkit Plugin See ditanauts QA plugin
- 17. Outcome
- 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
- 19. 19 Complexity measures over time (2) 0 20 40 60 80 100 120 140 Drive Replacement (Complexity)
- 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
- 21. 21 Other applications • Documentation complexity • Content inventory
Editor's Notes
- #2: <<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.
- #17: 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.
- #18: Weighting: no Cutoff score: no
- #23: 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.