Download to read offline
![+ + 925-956-4215 WWW.techprose.com [email_address] http://www.linkedin.com/in/paulatoth Questions](https://image.slidesharecdn.com/donthideyourcontentrev3090811-120118123140-phpapp01/75/Don-t-Hide-Your-Content-in-a-Traditional-Help-System-A-Case-Study-from-TechProse-Featuring-DocZone-25-2048.jpg)
More Related Content
Similar to Don’t Hide Your Content in a Traditional Help System: A Case Study from TechProse Featuring DocZone
![Vibe Coding vs. Spec-Driven Development [Free Meetup]](https://cdn.slidesharecdn.com/ss_thumbnails/vibecodingvsspecdrivendevelopment-251209105622-43f455e7-thumbnail.jpg?width=640&height=640&fit=bounds)
Don’t Hide Your Content in a Traditional Help System: A Case Study from TechProse Featuring DocZone
- 1. Don’t Hide YourContent in a Traditional Help System A case study for implementing a DITA-based HTML5 help system An independent consulting firm specializing in change management, documentation, and training The industry's leading cloud solution for creating, managing, translating, and single-source publishing of DITA content
- 2. Panel Moderator: DanDube (EVP Cloud Solutions, Really Strategies) Presenter: Paula Toth (Single Sorceress, TechProse)
- 3. DocZone : TheIndustry's First SaaS Solution for XML Content Management and Single-Source Publishing Mission: To provide the benefits of XML content management in a “Software as a Service” (SaaS) business model, without the typical overhead associated with large capital software expenditures or months of analysis. Solution Highlights: Foundation of proven, production-ready technology Completely based on open standards Subscription-based license model
- 4. Pre-translate content andalert translators How does it work? Vendor localizes DITA content with DocZone translation tool PDF EPUB Publish to all output formats for all markets HTML Help RTF No customer technology investment (just a monthly fee) Reduced localization cost and cycle time Collaborative review and approval Check content into DocZone server DITA DITA DITA Write/edit DITA content Create/store images Link with DITA content
- 5.
- 6.
- 7. Don’t Hide YourContent in a Traditional Help System A case study for implementing a DITA-based HTML5 help system An independent consulting firm specializing in change management, documentation, and training The industry's leading cloud solution for creating, managing, translating, and single-source publishing of DITA content
- 8. “ We change…whenthe PAIN of staying the same becomes greater than the pain of changing!” — Henry Cloud Our Client’s Pain
- 9. Time consuming publishing = Our Client’s Pain, cont.
- 10. Time consuming publishingInconsistent brand formatting = Our Client’s Pain, cont.
- 11. Time consuming publishingInconsistent brand formatting Content duplication Our Client’s Pain, cont.
- 12. Time consuming publishingInconsistent brand formatting Content duplication Inconclusive search results Our Client’s Pain, cont.
- 13. Delayed time tomarket Inaccurate and inconsistent documentation Low user satisfaction ratings Increasing support burden Result of Not Addressing Pain
- 14. Content duplication Topic-basedauthoring Reuse features for Topics Paragraphs Phrases Rows in tables Solution Key DITA
- 15. Reduce the publishingeffort Switched from Frame and MadCap Flare to XMetal authoring and DocZone CMS storage/publishing Automated publishing to PDF and online help Solution #1
- 16. Make the brandstyling consistent Applied consistent brand styling specifications PDF Online Help Solution #2
- 17. Reduce duplication Applieda content reuse strategy Reusable topics, paragraphs, phrases, table rows Conditions and filtering Solution #3
- 18. Make content moreaccessible Provided an HTML5 help system accessible on the Internet Framesets/iFrames Tables used for page formatting Services running on the server Plugins/Flash/Flex CHM Robohelp MadCapFlare Adobe Air Eclipse Help Solution #4
- 19. Totally open andaccessible to all search engines 5 modes of navigation TOC Breadcrumbs Parent and child links Related links Keyword search Solution #4, cont.
- 20. Supports browser forwardand back buttons Compatible with Windows XP & Win 7 IE 7,8, & 9 FireFox Chrome Safari Solution #4, cont.
- 21. Automated publishing Decreasedcost to update content by 15% Reduced time to output content From 16 to 1.5 hours for PDF From 4 weeks to 15 minutes for online help DITA reuse features Enabled authors eliminate content duplication Reduced the words in the repository by 50% Decreased the cost to update content by additional 35% Eliminated inaccuracies and inconsistencies introduced by duplicated content Results of Re-Engineering
- 22. Accessible HTML5 helpsystem Enabled users to search the Internet Provided immediate answers to questions Provided access to answers from any device Increased user satisfaction ratings Results of Re-Engineering, cont.
- 23.
- 24. Why not… Automatepublishing Reuse content Open help topics to search engines Make help available on any device + + Summary
- 25. + + 925-956-4215 WWW.techprose.com [email_address] http://www.linkedin.com/in/paulatoth Questions
Editor's Notes
- #2 I am Paula Toth, the best practices leader at TechProse—an independent consulting firm specializing in documentation, training and change management since 1982. I am here today to share with you some interesting things about online help systems we realized while we were on a project for a client, with whom we have been working for past several years. to begin with, let me give you some background so you can understand the situation that lead to the decisions we made about the online help.
- #5 How does it work? And how are we different from our competitors? 1) Unlike most of our competitors, we do not use a relational database under the hood. We use a native XML database that inherently understands the structure of the XML content being stored. This leads to excellent system performance, even as the amount of content and the number of users scale. Because of the nature of the XML database and the support for Xquery, you can perform operations such as “find all occurrences of a specific word within a <title> tag” and get instantaneous results...an operation that would require a lot of overhead processing for a relational database system. 2) When a user wants to create or update content in the system, they log in through the browser to our secure data center. After being validated as a user, they have the ability to access and update content in the system based on their role. DocZone is the only system to bundle in a fully XML-aware editing tool as part of the product (no additional cost). You also have the ability to use popular desktop XML authoring tools like XmetaL or Arbortext. Upon completion, they check the XML content back into the repository. XML components can be assembled into document “build lists” for publication. 3) Users also have the ability to create and store non-XML multimedia content for storage into the repository. (e.g., illustrations, movie files, sound clips, etc.) Because the system is built on a highly scalable XML database, the performance is excellent for storing massive files of this nature. These files can be linked to the XML content, using the Xlink standard. (These links can be preserved and exported out of DocZone if you ever decide to migrate to another system...DocZone has the most robust and standards-based linking architecture in the industry.) 4) Content goes through a collaborative review and approval stage. Since most reviewers are SMEs or developers, they may not need full access to authoring/publishing features. For these users, we have created a lower cost reviewer license, which allows for multiple reviewers to simultaneous review content through a browser and attach comments at the sentence level. The author can see all of the collected comments in one view and make the appropriate changes to the source XML, without having to re-launch the authoring tool! 5) Once the source language content (usually English) is approved, it can be forwarded to a “translation” workflow state. This is where DocZone really stands apart from the competition. We are the only XML CMS that has translation memory tightly integrated with the repository...your translation memory and XML content are actually the same thing. Other systems will typically identify changed XML components in English, and export them from the repository for the translation vendor to import into their translation memory tool. This is not the best scenario for end user customers: the same content is being stored in more than one system, you are dependent on the translation vendor to tell you what is a 100% match, fuzzy match, or what requires full translation, and it is difficult to work with new or additional vendors who may each be managing their own translation memories. DocZone handles it differently: when changed content gets forwarded to translation, the DocZone translation memory system preprocesses the content (e.g., substitute 100% matches for text segments, identify “fuzzy matches”, etc.) before the assigned translator even sees it. Rather than exporting content for the translator to import into a local translation memory system, the translator logs into DocZone and updates the translation from the browser. The content never leaves your DocZone CMS, and multiple translators and/or vendors are all updating one translation memory...which is maintained and controlled by YOU! This is a huge time and cost savings that often justifies the entire investment in DocZone. 6) Once all multilingual content is stored in the repository as “format neutral” XML, you can automatically render the content to whatever output format you like, in any language. This “push button” publishing approach provides tremendous process improvement and can eliminate desktop publishing costs, especially for the expensive Asian and bidirectional languages. We also provide two PDF publishing options: an XSL-FO tool (RenderX), and the higher-end composition tool (TopLeaf) at no additional charge, to handle more complex typographical requirements, such as change markup, complex tabular composition, and footnotes. 7) Finally, the biggest advantage to our SaaS approach is that you don't have to make a big up-front investment in DocZone. You do not have to pay any money for software licenses until the system is ready to use in production. And yet, you get to enjoy all the benefits and cost savings associated with storage of XML content, such as content reuse, streamlined translation processes, and single-source publishing.. When you put together the combination of immediate cost savings with no up-front software investment, you recoup your investment much more rapidly. Many of our customers tell us that they achieve ROI within 3 months of starting to use the system. In our experience, translation costs alone often justify the investment, with a typical reduction of translation costs anywhere from 40-70%!!!
- #8 I am Paula Toth, the best practices leader at TechProse—an independent consulting firm specializing in documentation, training and change management since 1982. I am here today to share with you some interesting things about online help systems we realized while we were on a project for a client, with whom we have been working for past several years. to begin with, let me give you some background so you can understand the situation that lead to the decisions we made about the online help.
- #9 We always start a project by identifying the pains involved and the ultimate result of not addressing them. Once this is deeply understood by all parties, the path to solution becomes clear. In this case, there were four major pains.
- #10 We had inherited a publishing workflow where the content was authored and stored in FrameMaker and imported into MadCap Flare to deliver a very nice help system. But it was very time consuming to publish.
- #11 … it was not a clean import. As you know, in FrameMaker, even though you have standard master templates and have trained authors to use them, when faced with deadlines, authors can choose to apply creative styling to individual paragraphs, characters, and even spaces. This meant that to get our text, graphics, complex table styles, and lots of little special characters all formatted correctly in MadCap Flare, we had to clean up the Fame sources. And even when the Frame files were squeaky clean, we still had to do too much hand manipulation in Flare and in the HTML output that was not possible to automate. Clearly, this was not going to be sustainable workflow. We would have to re-engineer this process. Now, there were several ways to re-engineer, BUT there is another pain to be considered.
- #12 Massive content duplication! It was built into the nature of the client’s products, as they all shared a core set of features and services. This caused the authors to copy and paste, duplicating content within documents and across documentation sets. The duplication was highly granular, and included copying rows in tables.
- #13 And finally the last pain, what good is having comprehensive documentation if users can’t find it! When we surveyed our client’s users, a vast majority of them said that when they had a question about using a product, they preferred to search the internet to get immediate answers. And, they want to be able to use ANY internet capable device search. Unfortunately, topics in our client’s MadCap Flare help were not findable on the internet.
- #14 So the result of not addressing these pains, was that -Product time to market was delayed, waiting for the documentation to be published -The documentation often contained inaccuracies and inconsistencies due to copying the content -Users were not satisfied with the documentation, even if they could find it -And instead of searching for answers to questions, users just called technical support
- #15 After analyzing all the pains, it became clear that resolving pain number 3, content duplication, was the key. The way we would resolve this pain would affect the resolution for all the other pains as well. What we needed was a way to support topic-based authoring, with content sharing features that included reusable topics, paragraphs, phrases, and even rows in tables. In our experience, due to the granularity of the reuse, making a commitment to DITA was the answer.
- #16 In detail, this is how we did it. We converted the content to DITA and switched from FrameMaker and MadCap Flare to XMetal and DocZone for content authoring, management, and automated publishing.
- #17 We separated authoring and publishing, and unified the brand styling throughout all documentation sets, applying the same style specifications to PDF and online help output.
- #18 We reduced the duplication by applying the reuse features available to us in DITA, including reusing ditamaps inside didamaps, topic reuse, conrefs, and DITAVal files for filtering content when we publish.
- #19 And one of the most notable things we did, was to put a good bit of research into building the help system. By interviewing product managers and experts for many traditional help systems, we learned that most help systems use frame sets and iFrames, or tables for page formatting, making it impossible for search engines to index the content in help topics. Some traditional help systems also use services on the web server that can require occasional resetting, causing help pages to be unavailable to users. And, if a help system uses plugins, such as Flash or Flex, then the devices used to view the help must have the plugins installed. This can be problematic for some corporations that don’t allow these plugins, or devices that can’t use them. So, to be totally open and accessible on any device, we built a straight, vanilla HTML help system that uses CSS for formatting and JavaScripts to deliver navigational behaviors. The CSS and JavaScripts reside in externalized modules, making them easily to maintain. The contents of these modules are only referenced by the HTML help pages.
- #20 LIVE SHOW AND TELL HERE INSTEAD OF THESE TWO SLIDES—USE THIS SCRIPT Show—Configuration Utility Overview > Meter Numbers Using the Configuration Utility > Laser & Thermal Waybill -TOC -Bread Crumbs -Parent and Child Links -Related Links -Search > Meter -Browser Back Button So let’s take a closer look at this HTML5 help. It has a simple clean interface, that can be easily customized to meet the needs of any project. It has 5 modes of navigation including a expandable TOC and breadcrumbs, which shows you where the current topics is located in the hierarchy of pages. It automatically populates topic links to the most immediate parent and child topics, without any link handling in DITA. It supplies related links if you use a DITA reltable. And, it has system-wide keyword search that highlights the keyword in the topic you are currently viewing. It continues to do this until you clear the keyword form the search field, even if you are navigating with the TOC.
- #21 The system supports the native browser forward and back buttons, And is compatible with -Internet Explorer 7, 8, and 9 on XP and Win 7 -As well as all the latest versions of FireFox, Chrome, and Safari
- #22 So, what have we achieved? After tracking the metrics both before and after our re-engineering project, here is the end result. JUST by automating publishing -We decreased the cost to update the content by 15% and -Reduced the time to output the content from 16 to 1.5 hours for PDF, and from 4 weeks to 15 minutes for online help The DITA reuse features enabled authors to -Cut the number of words in the repository in half, further reducing the cost to update the content by an additional 35%--That’s a total savings of 40%! -Reuse also eliminated the inaccuracies and inconsistencies caused by copying content
- #23 The openness of the HTML5 help, made the content accessible to any search engine from any device, enabling users to get immediate answers to their questions, any place, any time. The user satisfaction rating increased because users could finally find the content they were looking for.
- #25 In summary Why waste time with manual publishing techniques, when you can automate them with a one button push? Why copy and duplicate content, introducing errors, when you can reuse content? And why hide your content in a traditional help system, when you can deliver it in the cloud as completely open and searchable HTML5 help pages, accessible from any internet capable device? By using DITA, the DocZone native DITA CMS, and our HTML5 online help plugin for the DITA open toolkit, TechProse was able to reduce the cost of updating the documentation while simultaneously increasing the quality of the content and enhancing the user experience.
- #26 Any questions?