Entry #4 – Validation, Visualization, and Transparency: Creating the Tools and Culture for Content Quality
Company Name: EMC
Name of Submitter: Jason Holmberg
Email Address: [email protected]
1. Efficiency:
DITA is a robust information architecture that supports advanced content reuse, conditional information structures, and complex information linking to targets inside and outside a publication. The traditional table-of-contents (ToC) view presented by authoring tools, such as traditional publishing applications and XML authoring clients, does not sufficiently display the structure and relationships within modern publications intended for the web. Modern content developers are creating reusable, multi-purpose information maps that are sewn together by complex and varying relationship types. When content is conditionalized to serve specific user profiles, the difficulty in reviewing content – for company and industry standards, overall cohesiveness, technical accuracy, and functional DITA problems – increases significantly by the need to publish and review tens or hundreds of versions of a document. In the face of such complex content, organizations run a high risk of following inconsistent, ad hoc content review strategies and often have no means of scalably enforcing standards across functionally and geographically separated teams.
EMC’s IXT Team is comprised of information architects and software developers who create and deploy tools and processes to help content developers consistently deliver high-quality information products across a large enterprise. These tools are designed with the content developer and customer in mind, with a focus on increasing both quality and efficiency through an innovative approach to self-service standards reviews.
Validator – The Validator DITA OT plugin is a self-service component of EMC’s Standards Review workflow. Specifically, it generates an HTML-based report that allows writers and information architects (IAs) to review a publication for EMC DITA standards violations (technical and content). The IXT Team updates this plugin quarterly based on internal team review and feedback from our staff of content developers. Content developers provide suggestions for improvement through social media, which creates a customer feedback loop and acts as an “institutional memory” for continuous improvement as the users themselves suggest new standards review “rules” (i.e., known DITA combinations that are unsupported or problematic).. This tool helps prevent repetitive quality problems across multiple writing groups in DITA, while reducing the need for some resource-intensive peer reviews. See attachment 1 for an example.
Attachment 1. Validator content reports indicate problems to help prevent repetitive errors across a large enterprise, creating an “institutional memory”
Visualizer – “Visualizer” is a new DITA OT plug-in (and an HTML-based output format) that allows content developers to visually prototype the structure, relationships, and conditional behavior of a DITA publication in a browser. The old adage “A picture speaks a thousand words.” still applies; Visualizer reveals the full DITA information map to content developers and allows them to quickly review content cohesiveness, identify broken relationships, and prototype document variations with simple clicks to turn conditions “on” and “off”, revealing any problems that might surface with certain combinations of conditions selected. The tool is based on the D3 JavaScript library popular with data scientists, and Visualizer combines new visualization models with DITA content authoring to reveal the full structure of a publication and promote broad, consistent and efficient content review. Visualizer helps writers answer questions like:
- Are my publication’s topics well organized?
- Does my content include any intrinsic structural errors?
- Which topics link to which others?
- Which topics reuse content from elsewhere?
- How does the selection or removal of a condition change the overall content and structure of a publication?
Attachment 2. Visualizer Display of Complex and Conditional DITA Content
Transparent Content Review – To increase enterprise-wide collaboration during content development, EMC deployed review and collaboration software in 2015. This software allows information developers to initiate browser-based reviews with subject matter experts (SMEs) of their choice. This technology improves the quality and efficiency of technical review by centralizing review comments into a single interface (a web browser) where discussion among multiple SMEs can promote greater dialog and visibility into technical publications without the need to learn DITA. This model also avoids the confusing circulation of multiple PDF drafts and provides a workflow to concretely show that feedback from multiple sources has been seen, evaluated, discussed, and addressed.
By concretely implementing enterprise content validation, DITA structural visualization, and transparent reviews within the content development community, the IXT Team has created a platform to efficiently enforce content quality and promote effective collaboration and consistent workflow across disciplines. Use of these platforms is tracked internally, and Validator has risen to be EMC’s second most used output format (after PDF) while Visualizer is rocketing up the list since its release in June 2016. See attachment number three.
Attachment 3. Growth of Validator and Visualizer use at EMC
2. Customer Focus:
Validator is becoming a way of life at EMC. A few comments that have come in about Validator from internal customers include:
“Validator is great for error checking but also for a general report on the publication, quick way to scan / identify missing short descriptions … and other doc planning/management uses as well.”
“At VNX, we rely on the Validator results to keep our pubs in check.
“We had a massive amount of docs converted [from unstructured content], and we had a lot of issues initially with [invalid] tags. The Validator was an easy way to check for and rectify them.”
EMC has over 10 years of history creating profiled, technical content for customers, such as through our conditionalized PDF publishing engine or through our profiled desktop client (most often used for product installation procedures) called the SolVe Desktop. Visualizer was designed to support customer use of conditionalized documentation by allowing content creators to rapidly prototype document profiles with only a few clicks in the browser (versus past requirements to publish and independently review tens or hundreds of publication profiles). Combined with the capabilities of Validator and our review and collaboration software, Visualizer promotes quality, profiled documentation focused on providing tailored information to customers in their unique environments.
3. Transferability:
EMC’s Validator and Visualizer tools are DITA OT plugins that could be reused and customized by groups outside of EMC, allowing other enterprises to create effective, efficient, and evolving standards review workflows to improve content quality. Our company is currently reviewing the legal implications of releasing these products as open source offerings. Our lessons learned in deploying and supporting these tools could also help accelerate their adoption and effectiveness in other enterprises.
4. Innovation:
Validator and Visualizer are innovations that have fundamentally changed the content development workflow at EMC. Validator reduces the support burden of the IX Technology Team by allowing known DITA problems to be periodically encoded in XSLT templates. Content developers publish content to the Validator output format and get a customized report of known issues within their DITA, which is often maintained by a team. Team-developed content can be more prone to technical errors, especially where intra- or inter-topic relationships are involved. This innovation has become so popular at EMC that content developers and their managers now insist on clean Validator reports before releasing any content for customer consumption. Validator is a technical self-support tool, allowing content creators to find and address known issues without involving the IX Technology Team’s support staff, who can now focus on new or unique issues rather than addressing repetitive issues. EMC management believes this has contributed to a reduction in support volumes.
Visualizer is an innovation that combines content visualization techniques from data science with the complex structure and relationships of DITA-based publications, providing a novel and fundamentally new way to view modern publications as rich information maps rather than books. Visualizer was released in June 2016 but has already risen to be one of the top five most used output formats at EMC. Writers can now see the full structure and relationships within each publication, including technical problems (e.g., broken conrefs and xrefs). Visualizer also reduces the support cost of DITA publishing by providing important and at-a-glance visual insight into content scope, and it serves as a self-service support tool that allows writers to see structural problems and prototype how conditional changes add and remove content for known customer profiles.
Combining Validator, Visualizer, and review and collaboration software, EMC has established a new and industry-leading content review workflow that:
- empowers writers to pro-actively find and solve content problems in a cost-effective and scalable manner
- provides simple, browser-based review of content by SMEs
provides broad visibility into content structure and dynamic changes that can occur due to the configuration of conditional content
5. Transformational Value:
From Nancy Anderson, Senior Director of Globalization, Information Design & Development (IDD) and Technology: “In my role at EMC, I oversee the full content lifecycle for our technical documentation, from content creation through localization and the implementation of technology to support this lifecycle. Our team has been pushing boundaries in the Information Development arena over the past several years, continually striving to create an efficient, flexible production model with a backbone of robust tools and technology. This has allowed us to build an enterprise-scale DITA-authoring environment and community that effectively supports current business demands and enables the implementation of new tools and processes as those business demands change. Validator, Visualizer and our enterprise-level deployment of review and collaboration tools are great examples of how we have added innovative technology into our model to better support the business, improving the quality of our documentation and adding automation that streamlines processes.”
6. Leadership:
The IXT Team conceived of and developed EMC’s use of the Validator and Visualizer tools, as well as advocated for adoption of enterprise review and collaboration software for technical content review across the enterprise. Validator and Visualizer both required proposal creation, advocacy within EMC to solicit executive allocation of resources, socialization across multiple content development groups, documentation, and new support models to fundamentally change the way that EMC performs technical and standards content reviews. The team’s goal from the start was to turn content reviews from conceptual exercises,which can be broadly interpreted in practice, into experience-based and focused activities that save time and improve content quality. These tools have become broadly accepted and heavily used, transforming and modernizing the content lifecycle at EMC and providing a template for other organizations to follow.