By Scott Abel | Senior Member
In this exclusive interview for Intercom, Scott Abel, The Content Wrangler, discusses with Joe Jenkins of Oberon Technologies the changing nature of documentation and the impact interactive documents will have on the technical communication profession.
The Content Wrangler: Joe, thanks for sharing your time and insights with us. Let’s start at the beginning. What is an interactive document? What makes an interactive document interactive, specifically?
Joe Jenkins: In terms of documentation and technical content, interactive documents enable the dynamic exchange of information between the consumer of the content and the publisher. This is made possible via the device used to deliver the content.
Basic interactive documents like Web pages, email messages, and PDFs often include static hypertext links to additional content. Clicking on a hyperlink is the same as issuing a command to the Web browser: “Take me to this content!” More advanced, interactive XML documents can be made to follow complex rules and other business logic. This type of interactive document can be instructed to deliver, often automatically, content to the consumer based on specific interactions, behavior, customer data, and/or feedback collected.
Some advanced interactive documentation capabilities include:
- integration of XML content with machines via sensors (or other equipment) designed to automatically measure things like temperature, pressure, voltage, and provide measurement data as feedback
- decision logic that determines allowable values for input fields to ensure data validation and data integrity at time of data capture
- decision logic that determines appropriate content to be delivered based on inputs received during the execution of a task
- automatic delivery of content
TCW: Why do documents need to be interactive?
Joe: Not all documents need to be interactive, yet those written more in a procedural format are good candidates. Many forms of technical documentation are written to cover a broad set of material. For example, a service manual for a vehicle might contain all the information for all makes and models of that vehicle for a given year. It’s up to the service technician (the user) to determine which content is applicable based on the features—stereo equipment, transmission type, option packages, etc.—of the vehicle being serviced. This approach makes the service technician responsible for knowing in advance exactly what information is available and how to find it, which leads to confusion, frustration, and reduces productivity.
With interactive documents, a service technician could enter the Vehicle Identification Number (VIN)—or make and model of the vehicle being serviced—and then be guided through the technical content to the information relevant to repairing the vehicle being serviced. If we add additional filters to the mix, we can help the service technician diagnose the problem and repair it quickly. For example, a service technician could be prompted to enter a diagnostic reading, or we could read data directly from an on-board diagnostic device, and then push the appropriate service procedure(s) to the technician.
TCW: It’s clear that interactive documents can be designed to simplify complex service and repair tasks. Can you provide some examples?
Joe: Here’s one. Consider the procedure for “checking battery voltage.” If your instruction is:
Take a voltage reading on the battery and record the reading. If the voltage is less than 12 Volts, go to the “Check Battery Cells.” If the voltage is between 12 Volts and 14 Volts, go to the “Check Alternator.” If the voltage is over 14 Volts, go to the “Replace Battery.”
In traditional documentation example above, the service technician has to read the instructions, remember the voltage options, take the reading, record the results, and then perform the appropriate next steps. This type of documentation shifts the burden to the service technician. The technician has to read all the instructions and then determine which option he or she should perform next. It’s cumbersome, time-consuming, and inefficient. And, it relies on human memory, which is, at best, error-prone. When this approach fails the service technician, it leads to errors, potential re-work, wasted time, and lost productivity. In certain cases, the approach may create unsafe working conditions.
Interactive documents offer users efficiency gains over traditional documentation. The first efficiency gain comes from adding input controls that allow the service technician to record the voltage reading in the document. After the reading is recorded, the interactive document uses this information to display the correct next step to the technician automatically. This approach streamlines the process and provides a positive customer experience. This is only one simplistic example. You could take this example much further by embedding a voltage meter on the battery that can automatically record and communicate the measurement to the document, triggering the display of the relevant repair instructions to the service technician without their assistance at all.
TCW: What types of traditional documents should we consider making interactive?
Joe: The best candidates are things like procedures. Some candidates might include procedural documents where:
- the results of performing a step determine the instructions presented in subsequent steps (e.g., a diagnostic procedure)
- there are alternate configurations, like a repair procedure for a brake system that differs based on the specifics of the brake system (e.g., 9- or 10-inch brakes)
- the results of performing the procedure need to be captured to support audit and/or other compliance requirements (e.g., manufacturing batch records for pharmaceutical, maintenance procedures for aircraft, installation procedures for hardware/software) or to support enterprise decision-making (e.g., reports detailing standard repair times, inefficient step execution, and other business-critical data points)
- the input/readings for a procedure can be captured directly from the equipment (reading temperature values, on-board diagnostic/fault codes, pressure readings, other data able to be read by sensors)
- multiple departments or organizations need to perform the procedure and/or have access to the results of performing the procedure (e.g., when a field technician needs to interact with the technical support team in order to resolve an issue and the technical support team needs to know which parts of the procedure have been completed and the results of those steps to assist in developing a solution)
- the input is captured by one group and the results evaluated by another (e.g., a call center capturing information and an engineer evaluating the results)
- the procedures displayed are based on who the person performing the task is (e.g., where instructions are role-based)
Some document type examples include:
- Diagnostic procedures
- Maintenance procedures
- Operating instructions
- Repair instructions
- Batch records
- Manufacturing instructions
- Installation instructions
- Standard operating procedures
- Training material—certifications/assessments
TCW: What technology has Oberon Technologies developed to help organizations create interactive documents?
Joe: Oberon is currently developing a software product named IDeA (Interactive Delivery Application), an application initially targeted to field service personnel. IDeA enables repair and maintenance technicians to execute service procedures more safely, efficiently, and effectively through the dynamic delivery of diagnostic and service/repair information. Although field service is the primary target market, this product also has wide application among companies that need to communicate all sorts of operating instructions, maintenance procedures, installation steps, certifications, and assessments to those who need them. Organizations in automotive, aircraft maintenance, household goods/appliances, medical device, telecommunications, nuclear, mining, and manufacturing sectors will find many applications for the technology.
Traditionally, service technicians have access to information associated with many makes/models of equipment. Finding the right information specific to the equipment they are working on can be challenging. Using IDeA, the right content is delivered to the technician based on input and interactions captured from the technician (such as make/model of equipment and instrument readings) or from data coming directly from the equipment being serviced. All data associated with the executed procedure—instrument readings, steps executed, by whom, duration of each step, and the overall procedure, etc.—is captured in an integrated database to support analytics and reporting, enabling visibility into overall service metrics across the organization.
Currently, many companies with field service teams create technical documentation—service manuals, operation and maintenance manuals, troubleshooting/diagnostic procedures—using Extensible Markup Language, or XML. As its name implies, XML is a markup language that separates the content from the format, allowing content to be written independent of its output format (e.g., PDF, HTML, eBook, etc.). More often than not, XML content is used for creating publications in multiple formats (print, PDF, online help, HTML) from a single source. IDeA enables organizations to leverage their existing technology investments and extends the use of this existing content by providing additional markup that can be authored into the XML files to control interactive feedback (e.g., technician records a certain temperature reading or receives a fault code from a diagnostic tool) and determine the appropriate information to deliver next to the technician.
In addition to the interactive controls (text box, radio button, date field, pick list, etc.), IDeA also provides the ability for companies to embed business rules and validation controls into their technical content to allow for dynamic procedural flow based on input from the user (or from machine readings), and ensure data integrity at time of execution.
As interactions occur directly from the technician or from sensors or other machines, all the data associated with the executed procedure—instrument readings, steps executed, by whom, when, duration of each step, and the overall procedure, etc.—is captured in an integrated database to support analytics and reporting. Capturing data automatically and storing it directly in an integrated database helps to reduce errors and expedite the data collection process. Having visibility into the performance metrics of the field service team will allow for better decision-making in terms of new service plans/offerings, as well as identification of procedures/steps that may need to be re-written due to lengthy execution cycles.
IDeA provides the following business benefits:
- Enables field service personnel to efficiently and effectively perform service procedures
- Improves compliance with defined procedures, which limits risk, including injury and damage to equipment and property
- Ensures compliance with government standards and regulations such as OSHA, EPA, and FDA
- Enhances decision-making through integrated data capture and visibility into service performance metrics
- Reduces call center volume
- Decreases service time, allowing technicians to visit more customers each day
- Lowers IT costs (hardware, software, and personnel)
- Improves customer satisfaction by increasing first-time fix rates
TCW: How do we create interactive documents using your approach? Is there an authoring tool needed? A CMS? Do you sell a tool or are you somehow helping to make the documents interactive?
Joe: Leveraging interactive documents consists of two key parts: 1) creating/authoring the content and 2) delivering the content in such a way as to enable the interactivity to be applied during the authoring process. If you are not creating your content in XML, such as in unstructured FrameMaker or MS Word, then you likely won’t be able to reap all the benefits of component-based authoring and publishing, let alone interactive content. There may be ways to make this work, but it would require lots of unnecessary work, custom development, and significant funding that would leave you with a solution that is singularly-focused and not future-proof.
If you are using XML (either DITA or some other data model), you have already taken the first step toward interactive documentation. In some data models, such as DITA 1.2 and DITA 1.2 Learning and Training, many tags already exist to support interactivity (including userinput, choices, uicontrol, stepresult, lcQuestion, etc.). Additional tags can be added/specialized to support additional interactivity requirements. Therefore, no additional XML authoring tools are needed—just the knowledge of which XML markup is to be used to deliver the desired interactivity in the delivery application. Additionally, you don’t have to change the publishing tools and content management systems/repositories you use today. Neither do you have to change your processes. IDeA sits alongside your current technical publications architecture, uses your approved technical content, and delivers it in the right format to the consumer.
Figure 1 depicts a typical technical publishing architecture, where you have the content creators, illustrators, and subject matter experts creating and managing component-based content in either a content management system or file-sharing environment. A composition engine is used to create traditional outputs of PDF, HTML, eBook, etc.
Figure 2 shows that IDeA is integrated with your current content repository such that once a component/topic, or possibly an entire publication, is approved and available to be released, it is pushed to the IDeA repository. Once stored in IDeA, this content is immediately available for use by the IDeA delivery to an end consumer, such as a service technician. There is no additional content creation required for a delivery application, as IDeA dynamically publishes content directly from the authored XML source. So the ability to deploy content updates to all delivery channels is dramatically expedited and simplified. Additionally, IDeA has an integrated database that captures and maintains the data associated with executed procedures to support reporting needs.
TCW: What does the future of technical communication look like in a world where documents are interactive?
Joe: First and foremost, companies will need to stop viewing their core information assets as documents. And, they’ll need to continue moving to structured content comprised of self-contained components. Without this, the ability to create content quickly and accurately to serve customers will not be possible. This paradigm shift to component-based authoring is critical to exploit the advanced technologies available today.
The skills of the technical writer, both now and certainly in the future, will need to extend beyond just being able to create a well-formatted document. Understanding XML and component-based authoring will be required in order to meet the content creation and delivery needs of the future.
Joe Jenkins is a vice president at Oberon Technologies and has over 20 years of enterprise software development, implementation, and business consulting expertise in content management, automated publishing, and content delivery across many industries. He is responsible for overall product and business development at Oberon. In addition, Joe performs strategic implementation services activities including development of multi-year implementation roadmaps, conducting requirements workshops, and architecting enterprise solutions enabling content reuse, automated publishing, improved translation processes, and interactive content delivery. Joe is a frequent speaker at industry conferences on the innovative use of structured content to drive enterprise value.
