Adobe DITAWORLD 2019 – Day 3 Summary by Danielle M. Villegas

Danielle M. Villegas reporting here on the activities of the last day of Adobe DITAWORLD 2019. Like in the first two days, Stefan Gentz, Adobe’s Senior Worldwide Evangelist, and Matt Sullivan, CEO of TechCommTools kicked off and moderated through the day.

In this post

1. [Keynote] Leah Guren: Eels, Seals, and All the Client Feels
2. Garg (Adobe): This is not a chatbot. This is an experience
3. Herian (3M): How to Successfully Manage the Tsunami of Content and Tame the Wave
4. Piechowski (Briggs & Stratton): Migrating to XML Documentation for Adobe Experience Manager
5. Aschwanden, Quinn (Publishing Smarter): DITA Authoring and Publishing for Everyone
6. Preciado (Content Rules): Sneaking Structure
7. Anderson (IBM, OASIS): The State and Future of DITA – News from the OASIS DITA Committee
8. See you next year

Keynote: Eels, Seals, and All the Client Feels

Leah Guren, the owner of Cow TC, Israel, gave the keynote to open Day 3 of Adobe DITAWORLD. Leah says that she generally speaks about content development—which is an essential aspect of any technical writing, whether DITA is involved or not. But having heard her speak in person on several occasions, I can tell you that she is one of the goddesses of technical communication. She’s terrific in breaking things down in a relatable and humorous way for us to understand.

For the keynote today, she started with the story of some monk seals who had each gotten eels up their noses. At first, experts couldn’t figure out why it was happening. After some careful investigation, they were able to determine that the secret was in the naturally curious and sociable attributes of the animals. The seals were sharing behavior patterns copying one ornery seal who had gotten in trouble. And it was usually among the “teenage” seals.

The point of the story? Sometimes our clients make unreasonable documentation demands, bad choices, and poor decisions to content because it isn’t their job to know this stuff! They are often copying behaviors seen from another company in most cases, much like actions of the teenage seals.

Leah gave us eight funny yet real case studies from her many years of experience. She explained how we could relate this to our own experiences as technical communicators. The case studies included problems and solutions she encountered over the years. Some examples were with embedded help, graphics used incorrectly, inverted instructions, stolen Word files, lack of access to users for usability and content studies, lack of content strategy, and issues with change tracking. And by being an “eel by proxy”—copying the actions of others to look equal or better. In each of these cases, the client did something that we, as technical communicators, would think to defy logic in every way. Because the clients didn’t have the foresight to think about how they were creating or organizing their content. They were often following directions they had seen work for others, and blundering in their steps as a result.

Your clients may do stupid things, but that doesn’t mean that they are stupid. Maybe they didn’t understand document requirements. The higher up you go, the more public relations for technical communications public you need to do. We have to be tech comm evangelists to make internal customers and management to have them understand how important what we do is.

Your clients may try to shove an eel up their nose, and it’s your job to recognize this and, if possible, stop them.

This is not a chatbot. This is an experience.

How to fuel a chatbot with Intelligent Content and XML Documentation for Adobe Experience Manager

Tulika Garg, Senior Engineering Manager at Adobe, followed right after Leah’s keynote. Chatbots are the “new cool kid on the block,”—but the need for it seems overrated. Chatbots are already here. Our next generation is already starting to expect voice-activated chatbot exchanges, like using Apple’s Siri, Amazon’s Alexa, or Microsoft’s Cortana.

It’s happening now, and its popularity is rising. There is more acceptance of AI (Artificial Intelligence) chatbots by customers worldwide. Are we ready to maximize our experiences to position ourselves for success with this new technology? We’re ahead as content professionals due to our understanding of structured content. If anything, the “high-efficiency fuel” for chatbots is structured content.

Tulika provided us with the foundational basics of how AI analyzes natural language queries. Queries are based on utterances, which are interpreted by Natural Language Processing (NLP). NLP breaks down these utterances between intents and entities. The entities are the variables or metadata of these utterances.

So, in an example of an utterance of “I want to book Avengers tickets for tomorrow,” NLP would extract “book tickets” as the intent and extract the entities as “movie” (Avengers) and “date” (tomorrow). It might need additional entity parameters to determine where and what time, but you get the idea.

Creating a chatbot is about creating a content model built around intent, entities, and responses. You start with pre-defining the intent and entities. You would then tag content with these intents and entities, creating a metadata model. From there, you would define the structures and rules for the responses, and align them with the content structure and rules. Together, combining the metadata model and the content structures and rules would produce a viable content model.

As you think about how chatbots you are familiar with, such as Siri, Alexa, or Cortana function, you can understand how the query and response cycle would work. AI would gather those intents and entities. The idea is to get additional information in a conversational way to add more context to the question: More entities to narrow down to the specific answer the user is requiring.

A chatbot-ready CCMS would have structured content, a hierarchal metadata model at a granular level, and would serve granular content in response to complex over APIs.

At this point in the talk, Tulika provided a demonstration using Google’s DialogFlow. She explained how you can integrate with it and showed the entities, intents, and responses, and how you can train the bot. She also told us how to incorporate the content into the bot using Adobe Experience Manager and DITA XML.

How to Successfully Manage the Tsunami of Content and Tame the Wave

How 3M made the move from manuals to information products

Teeghan Herian, Technical Content Management Supervisor at 3M, gave the first Adobe customer presentation on Day 3 of Adobe DITAWORLD 2019. Teeghan explained that the main goals of global technical content at 3M are accuracy, consistency, and usability. They found that they were making 60 % more content assets each year, and they needed to be able to manage it.

They started by looking at the tools they were using. Most documents were in Microsoft Word. 3M switched over to Adobe FrameMaker because it had more technical documentation-specific features that more authors could use. Also, FrameMaker was more comfortable for the Technical Writers as well. Adobe FrameMaker also comes with native integration into XML Documentation for Adobe Experience Manager.

Working on the consistency problem was especially an issue in the review process, as feedback from one set of documents would affect the next set and so on, causing a tsunami of more reviews. In an internal study of their processes over five years, 3M averaged about 287 documents per year that would have each gone through at least three rework cycles, which added 27 days to process. If there were a spanning change in 400 documents to change one word, they’d have to change it, route the documents to review, and cross their fingers!

It was not an ideal situation. Even smaller changes, like a branding change, had to be done in 500 documents. And each document had to go through review again. (Read Bill Swallow’s talk from yesterday that goes into more detail about how to approach rebranding!)

Before making any sweeping changes universally throughout their systems, 3M started with a content re-use pilot using the XML Documentation for Adobe Experience Manager. The pilot involved just one division out of 24 divisions at 3M and included regulated content and eight spanning updates per year. They used Adobe Experience Manager Assets with XML Documentation for authoring, reviewing, translations, and then publishing globally.

They started with an inventory of all their documents. Next, they did an in-depth analysis. They compared similar documents and training materials to determine if there were any sections or statements that applied to all, some, or only one of the documents. From there, they created a process to develop components, review, assemble and tag the components, and produce a viable output.

The new method had fantastic benefits, as they ended up with 456 documents, which equated to 76 % reuse between ten primary product groups and three to five sub-category groups. Review time also significantly decreased, as the review effort was lower than before, and the time spent reviewing went down from over 100 minutes per item to fifteen minutes.

There was a change from a document mentality to a project approach, and creation and review times reduced drastically.

The process savings also extended to costs—in half before translation costs and savings for translation

Migrating to XML Documentation for Adobe Experience Manager

How and why Briggs & Stratton migrated to XML Documentation for Adobe Experience Manager to advance DITA use

John Piechowski, Director Dealer Support at Briggs & Stratton, USA, gave the second customer presentation on Day 3 of Adobe DITAWORLD 2019. Their initial goal was to produce responsive web manuals for their products, as they were already working in DITA (or so they thought). They learned that they were publishing web manuals that required significant effort with many unknowns. It prompted them to rewrite their goals to publish web-based manuals, improve translation processes, increase content reuse, and regain flexibility. The strategy also included moving closer to standard DITA Open Toolkit and standard DITA instead of specialized DITA.

They began with an existing CCMS that only generated PDFs and had no easy path to web generation. The structure was too rigid. Only about 50 % of their content was in DITA—and it was specialized DITA instead of standard DITA. Content reuse was minimal, and translation processes manual and painful.

Briggs & Stratton solved their issues by moving to “Standard DITA” (not specialized) and XML Documentation for Adobe Experience Manager. The web manual publishing process is now only three steps—generate, preview, activate.

The improvements were significant. Briggs & Stratton is working with TransPerfect for their translation needs. In the past, it used to take two hours to process all the files with their old translation process. But now, with TransPerfect’s GlobalLink integrating directly with Adobe Experience Manager, this time has been reduced to 15 minutes. Additionally, Briggs & Stratton has the flexibility to choose languages and other filtering choices as they publish. Content reuse has also improved immensely due to the Content Reuse Reports in Adobe Experience Manager. It makes it easy to measure and identify reusable items. Content governance improved with content across the board.

The learning process also yielded that they needed upfront and ongoing training and support for writers. Briggs & Stratton’s method is to migrate the content first to DITA, changing as little as possible. Once done, refine, identifying key governed content for reuse, and update references for a new structure.

Until today, Briggs & Stratton has migrated 90,000 items to DITA!

DITA Authoring and Publishing for Everyone

Adobe FrameMaker: What Adobe offers the DITA Author that no other tool can match

Bernard Aschwanden, CEO at Publishing Smarter, Canada, and his colleague Margie Quinn, Information Developer, followed with a “dangerous presentation.” Why dangerous? It was a live demonstration—no slides—of the best new features of Adobe FrameMaker (2019 release) and its integration and use with XML Documentation for Adobe Experience Manager. And done by Bernard Aschwanden, no less. Bernard’s presentations can be a whirlwind, and this was no exception, as he demonstrated about two hours’ worth of information in forty-five minutes! Fortunately, Margie Quinn kept him on track during the presentation. It went by REALLY quickly, so the summary here is a fraction of what they presented. I typed as fast as I could!

For more detailed review information, check out the Publishing Smarter website.

So, what do Adobe Experience Manager and Adobe FrameMaker offer that the competition doesn’t?

Within Adobe FrameMaker, you can:

• Customize your workspaces by arranging the User Interface as desired. If you reset the workspace, you can get a blank workspace.
• Use the “Feature Search” to find the functionality you need. Just hit the F7 key and start finding.
• Use shortcuts for UI control—guided environment if needed
• Create and update templates as you like to make them fit into your corporate design.
  • Authoring templates are separated from HTML5 publishing templates.
  • Publishing templates will work with the content and adapt it as needed for the output.
• Build expressions for “Conditional Content” by creating rules and values to manage attribute expressions.
• Save all your Publishing settings in STS files for sharing with colleagues and business partners.
• Convert entire DITAMAPs into PDF and HTML5.
• Include and exclude features as it publishes using DITAVAL.
• Give your content additional functionality and make your content responsive with HTML5 using specific layouts, and dynamic content filters. FrameMaker will help you look at tags and expressions and pull in what you want for the output. FrameMaker will automatically build the content filters into the published output.

The key change for Adobe FrameMaker (2019 release) that Bernard particularly emphasized is the significantly increased processing speed due to the new native 64-bit platform. With the power of XSLT and DITA Open Toolkit integration, you get a full-fledged DITA authoring and publishing solution.

According to Bernard, using Adobe FrameMaker is a matter of choosing the right tool for your environment. Adobe FrameMaker can do both unstructured and structured content while using XML Documentation for Adobe Experience Manager is pure DITA/structured content.

XML Documentation for Adobe Experience Manager has a simple-to-use interface, but it takes a different approach than Adobe FrameMaker. It’s user-friendly to Subject Matter Experts who are not familiar with XML and DITA. It makes online collaboration across the enterprise easy. Adobe FrameMaker, on the other hand, is designed for power users.

Bernard Ashwanden’s opinion on XML Documentation for Adobe Experience Manager is clear. It helps you to create a more streamlined workflow, enhances content reuse, makes shared reviews easier, gives you better translation management, and full traceability of changes.

You can log in to Adobe Experience Manager directly from Adobe FrameMaker, and check out and check in individual documents, maps, and descendants as desired.

You can also edit DITA content in Adobe Experience Manager’s easy-to-use DITA web editor. The web editor provides a streamlined view to see conditional text and make changes. The main advantage of Adobe’s DITA web editor is its user-friendliness and simple use. Even for Subject Matter Experts and Content Contributors who are not familiar with advanced XML editing and DITA. You can see the maps very clearly in Adobe Experience Manager for hierarchal structure, and drag and drop, promote or demote docs within the map. You do not need to use Adobe FrameMaker to publish everything. Adobe FrameMaker can publish with no problems out of the box. In Adobe Experience Manager, it’s easy to publish, but someone else has to set it up for you, and all you have to do is click “Publish.”

Sneaking Structure

Get ready for the future: How to bring DITA Best Practices to non-DITA Content

As has been mentioned several times throughout the conference, your content needs to be findable, scalable, and usable. Structured content is faster to create, easier to find, faster to understand, cheaper to localize, and faster to publish.

But some content remains unstructured. Or at least will stay “unstructured” for some more time. Regina Lynn Preciado, Information Developer at Content Rules (USA), knows that from her daily practice with customers. But even if your plans to move to structured content are still in the future, you can prepare for it—by “sneaking” structure into unstructured content.

Sneaking Structure into unstructured content can unify content across the structured and unstructured content. It can support consistent processes for content teams. It can improve findability and usability. It can help Subject Matter Experts in contributing content and make your content “future proof” by being “structure ready.”

Regina gave an overview of a structured content ecosystem to highlight what makes structured content great. However, her point was that DITA did not invent the concept, task, and reference information types, but rather, it used those as the foundation for a standard XML structure.

From there, she provided some best practices when creating unstructured content in a structured manner:

• Focus on the principles of structure. Consider chunking content by information type. Create shorter topics and use headings to start new topics. Start with basic information types, and then extend your information types.
• Label all the things for navigation, clarity, and relevance.
• Include keywords and phrases in headings, as well as text descriptions or captions for images and multimedia.
  • Be consistent, as customers crave consistency for usability, comprehension, and enterprise voice. Consistency builds unity by using and managing a common terminology and using a content model.
  • Include what your users need to know through clarity, comprehension, and navigation. Start strong and stay focused!
  • Reuse for governance, usability, and clarity. Unstructured. Copy/paste creates redundancy, and content drift occurs when an author edits pasted content, creating inconsistency and outdating it quickly.
  • Avoid dependent language, which depends on the reader to see other content to understand the relationship to current content, using time-relative words like “now,” “previously,” “currently.”

The State and Future of DITA

News from the OASIS DITA Committee

“It has become a tradition,” said Stefan Gentz, the host and moderator of Adobe DITAWORLD, to have Robert D. Anderson as the closing speaker of the conference. Robert is the DITA Open Toolkit Architect at IBM and co-editor of the DITA specification (HTML, PDF) at OASIS. He gave us the latest updates from the OASIS DITA Technical Committee.

In my opinion, this is a great way to finish things up after three days, as it provides fantastic insights into the direction that the DITA standards are heading. Also, it was a wholly platform-agnostic and vendor-neutral presentation that Robert gave. Kudos to Adobe for providing the OASIS DITA Technical Committee such a big platform to talk about their work. And as the information comes directly from one of the co-editors of all but one of the DITA specifications, we know this is the real deal!

Currently, the OASIS DITA committee is working on DITA 2.0. There was a conscious decision not to create “DITA 1.4.” Any standard going forward can’t carry the baggage from older versions. Backward incompatible changes cause technical debt. As new features improve on old, what happens to the old ones? The problem is that authors often don’t know what to use, and it’s hard to innovate around obsolete designs.

So, migration will be required unless you are not using DITA extensively. At a minimum, new doctypes at the top of each document will need to be updated. The main ambition of the committee is that this migration will be easy to do, and as painless as possible. But you don’t have to worry about preparing for migration just yet, as there is still plenty of time to prepare. Robert did suggest that as you look through your documentation now, you can prepare by looking over deprecated items, and updating those for quicker migration later. Some items have already been determined as deprecated items now in 1.x versions. As they sift through every proposal, they choose the ones that must explicitly address migration details and plans and show a cost-benefit for any incompatibility.

Goals for DITA 2.0:

• Simplification
• Reduce complexity
• Remove unused features
• Redesign hard to use features
• Where sensible, do things only one way

How will they do that? Here are some of the areas the committee is focusing on:

• Multimedia—new base elements for audio and video modeled on HTML5, and will be part of Lightweight DITA (LwDITA)
• New chunking, whereby chunk will either be “combine” or “split.”
• Removing rarely used elements like <exportanchors>, <anchored>, <anchorkey>, and others
• Revamping the use of <steps>. Instead of crazy workarounds to get steps within steps, OASIS will implement looser rules: <substeps> will be replaced with <steps> and other nesting tags like <steps-unordered>
• @outputclass used in CSS will become universal and integrated with DITAVAL flagging
• There will be a new <include> element for content parsed as XML or text and used for optional fallback content
  • Existing elements will be rebased, such as <coderef>, <svgref>, and <mathmlref>
  • Glossary entries will become more useful with additional elements allowed in terms, including subscript and superscript usage with the terms.
  • OASIS will drop (modular) XSD schemas. If XSD is needed, it’ll be easier to create RNG and generate a single (not modular) XSD. Even though you will still be able to deliver modular RNG and DTD if needed.

There is also some general cleanup going on with DITA. Some old inconsistencies are being resolved, like the class attributes for <linktext>, <shortdesc>, and <searchtitle>, and allowing <properties> in more contexts in <reference>. Hazard statements are being revised to make it easier to associate images with specific hazards or responses, as well as reorder without resorting to formatting customizations. Image maps will be easier to use. Lastly, indexing will be simplified by removing the <index-base> and <index-sort-as> and the <see> and <see-also> will become base elements (but still only visible inside index terms).

It’s not the final list of changes. Some items that are in progress and likely to be included but are still being sorted out—including modifications to bookmap to make them easier to use and more flexible. Attribute specializations, and <example> will become looser, and @lockmeta and @copy-to will be removed. Also, most uses of @domain will be removed.

Some items still need work and investigation. Pending items include <em> and <strong> tags. <simpletable> tag should work more like HTML, allow images and objects to vary, provide alternative titles in maps to allow you to specialize titles as appropriate.

What’s the timeline and progress on the technical content of DITA 2.0? Separate delivery of the DITA Technical Content 2.0 is already in progress. Troubleshooting design updates are just not fixable in DITA 1.3. Some bookmap resource updates add keys and resources.. The status is unclear at present about the “machinery task.” New learning and training will likely be a 2.0-compatible version with few new features.

LwDITA recently decided to base itself on DITA 2.0, but not just XML. The Committee Note for LwDITA is completed—all the initial details you could want! The specification for it is in progress.

The goal is to have the DITA 2.0 specifications done by next year. But that doesn’t mean that it’ll be approved at that time. As the committee is small, time is a factor! But it is coming, and hopefully coming sooner than later.

For more information on the DITA 2.0 work items that are open right now, you can check this OASIS DITA Technical Committee – DITA 2.0 proposals [PDF].

See you next year!

And that’s it! The fourth annual Adobe DITAWORLD 2019 conference came to a close, and the theme song played one last time until next year. It was full of information about how much DITA usage has progressed. Over 5,500 registrations for Adobe DITAWORLD 2019 are clear proof of the growing interest in DITA and the convergence of Marketing and Technical Communication.

I hope you’ve been able to enjoy these summaries. Videos on all the sessions will be available soon to relive all the fun and learning!

Related Links

Read also:

1. Adobe DITAWORLD 2019 – Day 1 Summary by Danielle M. Villegas
2. Adobe DITAWORLD 2019 – Day 2 Summary by Danielle M. Villegas