What your IT Doesn't Know about Publishing DITA Content
- 1. What your IT Team Doesn't Know about Publishing DITA Chris Nitchie Lead Software Engineer
- 2. "It's just XML. How hard can it be?" It's just tags We use XML for configuration all the time.
- 3. It's more complicated than you think. DITA is not just XML; lots of extra processing required Narrative XML requires more consideration that XML used for configuration.
- 4. Our Changing World of “Information” THEN NOW
- 5. Growing Demand for Mobile & App
- 6. Information is Transforming Maturity of information delivery approach EffectivenessofInformationDelivery Paper Documents Responsive, Adaptive Content Electronic Documents Intelligent, Interactive Content
- 8. The Content Life Cycle Author •XML/DITA authoring tools •Content templates Manage •Workflows •Life Cycle •Versioning •Reuse Management ('Where Used') Publish •DITA-OT •Simple XSLT •Vendor-provided publishing engines Deliver •Web Servers •Homegrown Web Applications •...? Established Products In-House Development/IT We spend a lot of time and effort choosing the right authoring tool and CMS system. We tend to under- estimate the effort involved in developing good HTML output. Too often what we deliver to the web doesn't take advantage of the value in the XML.
- 9. The Content Life Cycle Author •XML/DITA authoring tools •Content templates Manage •Workflows •Life Cycle •Versioning •Reuse Management ('Where Used') Publish •DITA-OT •Simple XSLT •Vendor-provided publishing engines Deliver •Web Servers •Homegrown Web Applications •...? Established Products In-House Development/IT XML XML NOT XML!AND THEN...
- 10. You content delivery strategy should take advantage of the intelligence in your XML source.
- 11. Simple HTML Transform XML Source DITA OT HTML Website!
- 12. Let's unpack this a bit XML Source Semantically rich Metadata Easily repurposed DITA OT Plug-in design and maintenance Publishing policies and procedures Publishing environment HTML Style standards Mobile readiness Metadata Website! Hardware and software stack Security Analytics Search Performance SEO Commenting
- 13. HTML Styling Default HTML output will almost certainly not be adequate (it's designed as a basis for customization) NOT MOBILE-READY At a minimum, you need to know XSLT, HTML, and CSS May also need Ant and Java Customizing the built-in XSLT can be challenging, depending on what you want to do. There are some third party plug-ins for more sophisticated HTML out-of- the box (e.g. dita4publishers html2/html5) Still meant as a baseline Often even more complex to set up
- 14. HTML Styling can be Complicated Brand and Style Standards Logos Colors Fonts Layout Details Mobile-readiness/responsive design Accessibility Search Engine Optimization HTML Metadata Regulatory Compliance
- 15. Search optimized for the intelligence of your DITA source Standard Web Team Options Use a public search engine like Google or Bing Use a Web CMS with search features What this misses Index should be DITA-aware, boosting keywords, index terms, and other tagged content DITA Metadata is lost if it's not represented in the HTML Public search engines can't index content behind a login Custom, home-grown search solution Often on top of an open source library like Apache Lucene, Elasticsearch, or Apache Solr Must be designed and developed specially
- 16. Commenting Standard options Open-source or SAAS commenting solutions, like Discourse and Disqus Web CMS commenting features Web CMS upvote/downvote features But: Comments are linked to HTML pages, not source XML documents Element-level commenting generally not an option Extra effort is required to map HTML comments to XML source You could go without, but think of all the valuable feedback you're missing!
- 17. Dynamic Filtering/Profiling DITA has rich profiling capabilities Sometimes this filtering is intended to show/hide content for specific audiences Thus "view-time" filtering can be a requirement in some cases Different visitors to the same content see it profiled differently You might even want to allow your users to specify which profiles to apply when viewing the content This requires that the metadata/profiling attributes in your DITA content be represented in the HTML, and that your HTML delivery can use them to filter on-the-fly No standard options for this one.
- 18. Analytics and Traffic Monitoring Existing tools only tell you about HTML traffic Extra IT effort required to map HTML statistics to DITA source
- 19. Security Base access control on DITA and CMS attributes Use metadata to match content to its audience Exclude content from people who shouldn't see it Content expiration Standard Website Considerations HTTPS Certificate management Security auditing Integration with corporate security LDAP SAML OAuth
- 20. Infrastructure Hardware and Software Stacks Simple web servers Apache IIS Nginx Etc. Web CMS Solutions Custom Web Applications Physical vs. virtual/IAAS servers Auditing of admin access and actions Software updates Uptime Failover Load balancing Log file management
- 21. Limitations of Pure HTML-based Delivery Any tool using your HTML output will affect that output, not the DITA/XML source HTML search engines will index the HTML, not the DITA Keywords and indexterms should probably be weighted more highly Relevant metadata not represented in the HTML is lost Metadata and taxonomy used in your content should be available for search HTML Analytics tell you which web pages got traffic, but not which content got traffic Which DITA maps and topics get the most traffic? When people search for certain words or phrases, do they find the right topics? HTML comments are linked to the HTML, not the content What are people saying about this topic? All of this requires custom tooling to map HTML-related data to its source.
- 22. So you do all this stuff DITA OT Plug-Ins/XSLT Transform Conforming to corporate standards and style guides Supports desktop and mobile Searchability Third-party search engine or self-managed Commenting Profiling Analytics With traceability to source XML Security Server environment and infrastructure
- 23. And then you need to publish an update.
- 24. Staying Up to Date - Things to Consider How many steps are involved in getting updated content from your CMS to your website? How many people are involved? How much lead-time is required by the web team to be able to update the content in a timely manner? Authoring Group Updates Content Delivered to Web Team Converted to HTML Uploaded to Website Third-Party Integrations (e.g. Search, Analytics) Updated New Content Required
- 25. Publishing Policies and Procedures Authors directly publishing from the authoring tool Publishing system integrated with the CMS, triggered Manually Workflow steps Life cycle states Manual publishing with the DITA-OT Authoring group? Development team? IT team? Somebody has to own this. Automated builds using a Continuous Integration system like Jenkins Manual builds Automated nightly builds
- 26. Current Delivery Process Architecture IT and/or Web team support is needed to complete the delivery process for initial upload and with every update
- 27. Current Delivery Process Architecture IT and/or Web team support is needed to complete each additional process
- 28. Current Delivery Process Architecture Demands on IT and/or Web team quickly reach an unmanageable state • Resources are strained • Content accuracy and quality is severely impacted • Timeliness suffers • Customer satisfaction deteriorates
- 29. Aspects of DITA Delivery DITA Delivery HTML Conversion Web Hosting Update Process Search Analytics Commenting System Maintenance Real-time Filtering
- 30. None of these things is insurmountable, but you must account for them in terms of time, money level of effort, and budget
- 31. Towards a Sane Delivery Workflow
- 32. DITA Web Delivery Requirements Agility - Quickly, easily, and cheaply update publically-visible content Mobile-ready Searchable Performance - Handle high-traffic loads Security - ensure users see the right content Commenting/feedback - what do users think of the content? Reporting and analytics - who's looking at what? How often? With what kind of device?
- 33. Expectations A single system for online visibility to all approved product and service information Automatically synchronize content from a variety of sources into a single repository of consumer-accessible information Deliver exactly the content needed on any device with a minimum of "clicking around" Collect feedback to help identify new opportunities
- 34. Sync Intelligent Content Delivery Streamlines the Current Architecture Create & Capture SAPCRMFile System CMS Authors Illustrators Reviewers SMEs ? Store & Manage Publish & Deliver Format Publish to Print Post to Web Mobile & Apps Help System Portals Cloud-based Searchable Environment Transform Package/Brand Intelligence Maintain Capture feedback Analyze use PDF Content Delivery
- 35. Thanks!
Editor's Notes
- #5: Let’s start by talking about the changing nature of information in our connected world. Today’s information consumer are increasingly accustomed to personalized, digitized information Whether they are traveling, in their home, at work, or even while exercising …
- #7: Documentation is also Transforming – to higher levels of Maturity and Effectiveness Paper Documents (Static, pre-published page-based documents, manuals, guides, etc.) Electronic Documents (Static, pre-published page-based documents and HTML. Still pages on the web) Web & Mobile, (Richer media (3D graphics, animation). Still lots of full publications. Often Requires Unique tools for each delivery mechanism Intelligent Content (Suitable for multiple devices. Personalized content. Enables self-service and interactivity) Present typical content lifecycle has consisted of create, manage, publish and deliver. In a print-based and book driven model, publish and deliver were 2 distinct processes (e.g. companies or printer houses would publish the documentation products and then they would be distributed/mailed to the consumers). Even with PDF publishing, this model hasn’t really changed as people have still thought of their documentation as books, and therefore publish all flavors of their books and then distribute and/or make them available on their website. Could possibly re-purpose the above slide to help tell the story and show the progression of content from static print to intelligent, dynamic content
- #35: Authors: Illustrators: SMEs, Reviewers: Content Management Repository Publishing Engine