tl;dr Vivek Kumar, Director of Products at Adobe kicked of the second day of Adobe DITAWORLD 2019, followed by the keynote from Loni Stark, Senior Director, Strategy & Product Marketing at Adobe. After that followed practical and real-life customer presentations from Mitel, BlackBerry, and Palo Alto Networks about the use and implementation of DITA with Adobe FrameMaker and XML Documentation for Adobe Experience Manager—Adobe’s DITA Component Content Management System. Chad Dybdahl from Adobe talked about collaborative online review and Bill Swallow from Scriptorium Publishing discussed corporate design and rebranding strategies based on DITA.
Danielle M. Villegas reporting here on the activities of DITAWORLD 2019, Day 2! After the familiar DITAWORLD theme music played, we started the day! Like yesterday, Stefan Gentz, Adobe’s Senior Worldwide Evangelist, and Matt Sullivan, CEO of TechCommTools kicked off and moderated through the day.
In this post
Changing the World through Digital Experiences
Vivek Kumar, Director of Products at Adobe, kicked off the day with a quick introduction for the day, starting with this quote from Shantanu Narayen, CEO of Adobe: “People buy experiences, not products.”
Content is integral to the customer experience—can’t separate it from products. If customers do not have an excellent post-sales experience, they’re likely not coming back. That’s where content makes a difference.
What makes the content experience great? Content should be searchable, consumable, socially enabled, relevant, personalized, and consistent.
What helps organizations create and deliver great content experiences? Several of the talks today (see summaries below) will be sharing the methods they used to make these happen for their companies and clients.
Keynote: From Marking Digitalization to Fluid Experiences
Why understanding your content’s future is the key to success
Loni Stark, Senior Director, Strategy & Product Marketing at Adobe delivered the keynote on Day 2 of Adobe DITAWORLD 2019. The latest digital experience trends show that digital experience consumption is increasing. The bar for more personalized experiences is rising quickly, and people are all over the place are putting more emphasis on the customer journey.
Case in point: in a recent study, half of all Americans use two devices at the same time constantly or frequently, and they used these devices more than eight hours every day!
The decision-making process is now a circular journey—active evaluation, or the process of researching potential purchases; closure, when consumers buy brands, and post-purchase, when consumers experience them.
The critical points for mastering the digital experience across the customer journey involve reach, which is the ability to deliver a message in the most optimal fashion possible, and engagement, which is anticipating the next best response or experience.
Reach means reaching all senses. Visual (text, image, video, VR/AR) and audio (voice) senses, but what about touch and smell? It’s all about inherently interactive content and the adaptation of content to its device or environment. Fluid experiences enable omnichannel delivery at scale, with new ways to store, manage, and measure content and how it could behave. Structured content could be created, managed, and delivered to any channel as a store locator, a Q&A/FAQs page, or, e.g. a contact info list. The trick is making it channel-agnostic information.
Immersive content is becoming more predominant. VR (virtual reality) and AR (augmented reality) are emerging rapidly. Audio/Chat is growing at a faster rate than mobile adoption! Embedded interactions are becoming more commonplace.
Engagement is about the first and next best response/experience and repeating that process. To do this, we can:
- Meld data and insights to the content engine
- Augment human creativity with Machine Learning (ML) and Artificial Intelligence (AI) powered by Adobe Sensei. Sensei is a technology used to help speed up mundane tasks, and process live-data for more relevant information.
- Personalize by connecting brand identity and individual intent & desires.
Loni quoted Thomas Edison by saying, “Vision without execution is hallucination.”
How do we continually drive personalized experiences? It’s about optimizing the content journey and including AI and automation as part of the performance to improve the experience.
This is not a review. This is an experience.
Making collaborative review easier for Subject Matter Experts (and you!) with XML Documentation for Adobe Experience Manager
He then backtracked a little bit and said that some manual processes are good. Reading a physical book can still be something enjoyable sometimes, and some get value out of it. Handwritten notes or letters are something else from which we can derive value. Listening to music on vinyl also is a manual thing that has value. Modern alternatives are good, but not always better.
Some processes that are not as good include handwritten edits received from SMEs (Subject Matter Experts), manually incorporated edits, hard copy prints, edits put in the technical editor’s physical inbox on their desk, receiving handwritten edits from a technical editor, and the cycle that continually ensues in this manner.
When you hear, “We’ve always done it this way,” with this process, the problems that glare at us include no visibility into the process, significant manual effort, opportunities for errors, a process that is paper-intensive, and involves physical storage.
For a more modern twist on the same thing would be authoring in Word, emailing documents in review, dozens of reviewers/copies, and changes manually made in the source. It might seem a little better than a red pen and a hard copy, but it has its problems. This modern version is chaotic and uncontrolled, where reviewers can’t see each other’s comments; there are still opportunities for errors, and you’re using Word.
However, DITA alone is not the answer.
It’s about the money—ROI (return on investment) that comes from eliminating barriers for better content overall. These barriers include:
- Manual process management and tracking
- Error correction from manual or copy/paste changes
- Operational and storage costs
- Speed to market
- Lost productivity
This also includes things that are harder to quantify, such as:
- Increasing productivity and job satisfaction
- Decreasing bottlenecks
- Improved collaboration
- More engagement from SMEs/Reviewers
- Higher quality content
But, if we think about one more process in which writers are authoring in DITA, use “Review PDF” from DITA Open Toolkit, email the output to reviewers where feedback comes back as PDF comments if you’re lucky, and then you can make changes manually in the source—it’s a little bit smoother!
But can’t you just send me a Word doc? (Just say no!) Using Word is still chaotic. Reviewers want context, and they can’t do that if they can’t see each other’s comments, there are opportunities for errors again, manual incorporation of changes, and little to no traceability.
Collaboration is king! Chad gave a demo in XML Documentation for Adobe Experience Manager to show how collaboration works in this CCMS. You can create reviewing tasks and even have reviews going in parallel. And you also include reviewers outside the Adobe Experience Manager platform.
Adobe FrameMaker Publishing Server as a Publishing Engine for DITA Content
How Adobe FrameMaker helped Mitel to customize DITA Output Templates in a Day and automate publishing with Adobe FrameMaker Publishing Server
Mitel is a global leader in business communications and collaboration. Chander Aima, Sr. Manager Technical Publications at Mitel, and Ramabhadran P, Documentation Manager at Mitel, were Mitel’s representatives at DITAWORLD 2019. The Technical Documentation team at Mitel began their journey to XML Documentation for Adobe Experience Manager last year, and they needed a central repository for DITA Content. They chose to migrate their legacy content to DITA and Adobe Experience Manager. Their next challenge was to customize DITA Outputs.
In the DITA Open Toolkit workflow, they transformed their content from DITA to XHTML/HTML5 with XSLT. This process was time-intensive and needed developers and XSLT and CSS development. In their new workflow, they are using Adobe FrameMaker and Adobe FrameMaker Publishing Server to author, render and publish DITA. Now they can design the templates in an intuitive, visual WYSIWYG environment.
Adobe FrameMaker Publishing Server (2019 release) Support was optimal, as it provided DITA DTDs, a WYSIWYG authoring environment, structured authoring templates for DITA, publishing setting output for DITA, but also several different customizations.
Their PDF Output Customization process was the following:
- Open the ditamap in Adobe FrameMaker.
- From the File menu, choose Publish.
- Create a new STS file.
- In Outputs, click PDF.
- Click the DITA Options tab.
- Select the Save PDF via Book with Components Route checkbox.
From there, you can customize the templates, then import the templates back to the STS file, click save and close.
You can also use STS files to store all your HTML5 settings. HTML5 Output Customizations are done at the screen layout level and content pane level. The method steps are:
- Open the ditamap.
- From the File menu, choose Publish.
- Click Edit.
- Click Responsive HTML5.
- Edit Manage Layout.
- Select the override styles for the output checkbox.
- Import your customized CSS file.
Mitel also offered the following resources that can help with troubleshooting issues:
- FM Screen Profiles
- W3School Tutorial
- Browser Inspect Editor
- DITA Open Toolkit Error Messages
They also did a short demonstration of Adobe FrameMaker Publishing Server so people could see how it integrates with Adobe Experience Manager as well.
From Opportunity comes Innovation
How XML Documentation for Adobe Experience Manager gives BlackBerry the power to innovate
Marco Cacciacarro, Senior Technical Writer at BlackBerry, delivered a presentation this year as a sequel to a talk that Marco gave last year at DITAWORLD 2018. He followed-up on activities that BlackBerry had done since launching with Adobe Experience Manager. You can find the results of the work done at https://docs.blackberry.com, which is where the documents for all BlackBerry software resides.
The main challenge BlackBerry faced was that they had a long CMS history. During a period of significant transition, CMS and web support structure crumbled, documentation got stuck in status, so the solution was to get a new CMS.
Why was Adobe Experience Manager the solution? It’s a fully-featured CMS that plugs into a complete web platform. It met or improved on their feature requirements, eliminated the web “middle-man,” provided a browser-based DITA management and authoring platform, has built-in map and topic authoring tools, is fully integrated with the web front-end, and gave them complete control over the full content creation process.
BlackBerry was on their own when creating their “DIY” migration strategies. While the process was both intimidating and exciting, the DIY approach made them a stronger team.
Their strategic approach included:
Dedicated working groups
- Breaking efforts into measurable tasks
- Each group had a specific focus
- Volunteer-based on interests
- Define tasks to fit and overall schedule
- Opportunity to develop expertise
- Solutions through collaboration
Streamline processes and requirements
- What you need versus what you are used to
- Opportunity to enhance what works, discard what doesn’t
- Changing attitudes and experimenting
Develop relationships within your company—most important!
- You will have to deal with skill gaps
- Develop relationships to bridge those gaps
- Internal relationships set you up for future success
How has XML Documentation for Adobe Experience Manager given BlackBerry the power to innovate? Marco showed how they do many of their editing tasks in the Adobe Experience Manager web-editor through a demo and included the review process, building a map, building a product page, then rollout, verify, and publish live. It’s all pretty seamless and easy to use with templates.
The innovative lessons learned included:
Highlighting customer success stories
- Learned from Adam Toporek’s “Be Your Customer’s Hero”
- Customers use docs to evaluate the business value
- Our docs don’t address real-life use cases
- Discovered a marketing repo of success stories
- Break down silos, and
- Link to those stories
Use metadata to improve the search experience
- Integrated the Coveo search engine
- Started with a basic keyword search
- To enhance, we need metadata
- A full metadata taxonomy would take time
- Leveraged metadata we already use for PDF/HTML output
- Improved search with searchable identifiable searchable items
- The previous site used direct links from software to predictable URLs
- This model didn’t translate
- We can create whatever URL path we want on our site
- Now we use static redirects
- Direct cooperation between docs and dev with no web middleman
Experiment with content design and architecture
- Web templates are flexible
- Breaking down large monolithic guides
- Workshop a new way to guide customers to scoped deliverables
- No further web development required
- Another take on the concept: Experiment with the design to break out information in smaller blocks, and don’t change anything of the backend to make it more flexible
Experiment with content workflows
- Our job is to help customers when they are frustrated
- Anticipate customer hassle; try a conversational tone
- Video content was falling out of date
- Experimented with a workflow approach
- The alternative to traditional docs: minimalist, conversational steps, screenshots, take the complex and make it simple
- Active your device and install blackberry work
- Focus on minimalism
The next steps for Blackberry are working on implementing Adobe Analytics and improving the accessibility of the content.
From Vision to Success
How DITA and XML Documentation for Adobe Experience Manager Empower Organizations with Supreme Control Over Their Content
Julian Murfitt, CEO at Mekon, and Dave Harrison, Project Manager at Mekon, continued with the learnings from a couple of real-life projects. Mekon was founded in 1990 with 30 consultants and developers leveraging XML technology to help customers turn content into a business asset. Their customer-focused, can-do attitude includes doing strategic consulting, information architecture analysis, solution prototyping, system integration (Adobe Experience Manager, API, etc.), stylesheet development, and training and coaching.
Their process follows four basic steps:
- Assess – Content Strategy Audit
- Design – Solution Design and Planning
- Prototype – Conference Room Prototype
- Implement – Iterative Implementation
This is a case study that looks at three of their customers who moved to XML Documentation to Adobe Experience Manager.
XML Documentation for Adobe Experience Manager is a DITA CCMS and builds on top of Adobe Experience Manager Assets, which is central to your technical content creation and management. The key is to create a roadmap to construct the rollout following the process listed above. It’s not a short process! It can take at least 12 months, more or less, depending on the size of the project.
Key challenges Mekon’s customers wanted to address and their solutions:
Challenge: Stability – Existing systems were unstable and prone to errors, and it was hard to make changes to the systems due to multiple legislative changes. The client knew the end of life for the previous system was approaching.
Solution: More than 95 % of the customer requirements were met using standard out of the box functionality, enhanced information architecture, and a stable environment with an improved support model.
Challenge: Morale (motivated team) – Teams were “firefighting” issues. They were stricken with the inability to meet timelines and pressure to respond. They felt like they were continually reinventing the wheel and fixing same things multiple times, with limited opportunity to improve and develop both products and people.
Solution: The new CCMS enabled the authoring team to implement a new strategy and rekindled enthusiasm. A team where many were ready to quit is now a team still in place two years on!
Challenge: Response to change (having good scalability, address customer needs) – Financial crashes drove multiple legislative changes to 20–25 per year, taking at least a week to turn around. The process was complex and multi-step (15 steps), and couldn’t respond to stakeholders effectively. PDF publishing would take an average of three hours.
Solution: By improving the granularity and flexibility of metadata, it enabled faster updates and better reuse. Enhanced architecture reduced PDF publish time to two minutes, with an overall cycle time for changes down to 24 hours from a week.
Challenge: Managing updates – The client’s annual print cycle required updating 65 publications. Temporality—time/date validity was an issue as accountants needed to comply with a correct standard depending upon the date on which accounts are filed.
Solution: While it was a complex area to model, use of date variants were created to include start and end dates to support hierarchal date filtering. A filtered DITA output applied a date-filtering pre-process plug-in to a chosen ditamap to product DITA filtered to a specific date combination by standard, topic group, etc.
Challenge: Authoring experience – Clients needed easy to use, intuitive tools. They were used to poor interfaces for power users, difficulty with change, and poor governance. SMEs’ ad hoc usage of Word and the difficulty using XMetaL and Arbortext didn’t help things.
Solution: Provide good tools for power users (Adobe FrameMaker or Adobe Experience Manager’s built-in DITA web editor). Then, create a folder structure that can be replicated to allow same look and feel. Eighty SMEs/Engineers needed an easy-to-use interface. DITA WYSIWYG editing can be delivered using Adobe FrameMaker.
Challenge: Publishing – Attention to detail was critical. Multimedia publishing was required. Stand-alone documents (60–70 pages on average) were taking three hours to publish. It was also hard to publish to the website, and Word output was a requirement for third-party suppliers.
Solution: Take a similar, consistent approach to all publishing — attention to the granularity of content improved delivery. Stand-alone publishing time came down from three hours to two minutes. Bound volumes reduced to 28 minutes. Adobe FrameMaker Publishing Server became part of the ecosystem. Mekon also developed a plug-in for Microsoft Word.
Challenge: Reputational risk – protecting the corporate brand – Customers could see that the response to updates was slow, especially post-financial crisis legislation. Error identification in content was difficult, and detail was vitally important. Something as small as a missing parenthesis could have a significant impact on meaning!
Solution: Adobe Experience Manager made it far easier to find and identify errors in content and isolate them. Reuse meant fewer issues from copyright, watermarks, icons, ellipses, and graphics. Having a defined reuse model and search capability allowed better customer response, which led to a better reputation.
Challenge: Future opportunities – Hard to find, legacy systems were not easily searchable. Sharing content with third-party suppliers proved difficult.
Solution: The use of Adobe Experience Manager improved the “findability” of content. Applying Metadata and a new taxonomy integrated with Adobe Experience Manager helped as well. Moving to DITA made it easier to share content and enhanced management reporting. It also helped users by adding markup like “Reason for Change” and other enhancements.
Mekon determined that the migration success factors included:
- Establishing an information architecture and a migration strategy focused on granularity, reuse, versioning, and governance.
- Involving change management by winning hearts, getting senior management backing and a senior sponsor, setting clear goals and decision-making processes, keeping plans and progress visible, and making transformation accountable by setting performance goals.
- Securing sufficient resources—especially for testing.
- Partnering with experts—consider what tasks you can outsource.
- Don’t take TOO long!
Customer outcomes showed that a typical implementation takes 9–12 months to complete.
- The time needed to change content came down from one week to under 24 hours.
- The change process for authoring came down from fifteen steps down to just three.
- The PDF publishing time reduced from three hours to three minutes.
As a result, staff morale turned around. Customers found that 95 % of the out-of-the-box functionality of Adobe Experience Manager served their needs, and it was able to handle critical timelines. Customers said that Adobe Experience Manager is stable, scalable, and very capable. It helped to drive productivity and creativity.
Operationalize your move to DITA with Adobe FrameMaker and Adobe Experience Manager
Building the business case and processes to make this transition successful
Why DITA? The classic, non-XML FrameMaker document didn’t scale. They found that their current processes were too time-consuming, prone to errors, and had limited graphics and media quality. Translation costs were high, and not much focus was on the quality. Add to that the system crashes, customers complaining about the bad graphics, no opportunities to add metadata … it was a recipe for disaster.
They knew the solution would be a unified content experience, with searchable content, dynamic linking, and multiple outputs for customers. It would focus on creating content, pre-validating content, and providing consistent output for content creators effortlessly.
To get started, they knew they needed the following:
- Buy-in from upper management (they worked with Adobe as beta testers)
- Be able to identify the phases and planning the change management process
- Adobe Experience Manager developers to build the HTML templates and CSS styling
- A vendor to help with the automatic conversion of content to DITA
- A vendor to set up DITA Open Toolkit for PDF generation
- A resource to help with manual DITA validation, keep content in sync, and web publishing
- Training the writing staff for structured authoring
There were three stages for their content migration. It was time-consuming and not easy!
- Pre-conversion – They needed to make copies, import tags from the new template, delete any legacy formats, retag content for a topic-based structure, identify and rename duplicate headings, review the work, zip up the work, and finally send for conversion.
- Conversion – They used a conversion vendor to auto-convert the content, which would return structured files containing bookmaps, ditamaps, and XML topics.
- Post-conversion – The final phase involved manual DITA validation, and PDF diff to bring content into sync. They also had to follow book publishing processes to cut over from unstructured content to a structured book on the website, while archiving older information as an “unstructured book.”
The entire migration took two years. It took the first year to go live with the first structured book. With the competencies built from that, it took only another year to structure the remaining 90 % of the content repository.
Sunitha then gave a demonstration of the structured content from upload, using XML Documentation for Adobe Experience Manager to generate output.
Streamlined workflows enabled better agility for remote publishing, individual topics, single sourcing, and bulk tagging. It also offered translation cost reduction, pre-validation, separation of style from content, consistency, and compatible UNIX commands for global changes.
The migration also helped measure customer engagement. They implemented Adobe Analytics to measure site adoption and check whether the adoption of this new documentation was at pace with new customer acquisition. It helped them identify the most used topics, identify customers and regions that were top users, and learn about the customer journey.
The advanced DITA capabilities of XML Documentation for Adobe Experience Manager allow Palo Alto Networks to explore advanced DITA concepts and Adobe Experience Manager features to simplify complex content, such as conref for content reuse, DITA profiling for filtering content, keys to create reusable topics and maps and use Adobe Experience Manager to generate HTML for translated content.
You can find the final results of this endeavor at https://docs.paloaltonetworks.com.
Simplify your rebranding efforts with DITA
How to rebrand your content in hours instead of months
Rebranding might get a new look, but it also means everything has to change.
The most common reasons to rebrand usually involve company acquisition, a company image makeover, a new product/service division, OEM/Partnership content sharing, or just pure whimsy.
You might say it’s a one-time effort. Highly unlikely. It is more likely to happen frequently.
What can change? It’s not just visual design, like logos, colors, and layouts. It also can include fonts, imagery, delivery formats, company name, product names, feature names, copyrights, legal disclaimers, and contact information.
In an unstructured approach, it would affect many individual files, maybe a template, perhaps adherence to the template, and lots of copied and pasted boilerplate content that people might not be using right in the first place. The unstructured approach is making changes to each file individually. You need to create new templates and apply them to all documents. Formatting overrides may break automatic migration. And finally, you need to republish all documents. It’s a very manual rebranding process, with large amounts of time for no other change than look and feel. In the best-case scenario, the updates would be minutes per source file or hours per publication. The more likely scenario would be hours per source file or days/weeks per publication.
The DITA approach to rebranding:
- Separate the formatting from the content. Tag semantically to give content a purpose or identity. Branding falls under information architecture and publishing scenarios, not content development. Let technology do the heavy lifting—content isn’t changed this way. All the formatting is done through CSS or other style files, and you can continue with your content as you have.
Stylesheets (transformations) This includes XSLT transformations with DITA Open Tookit. This is where you are making all your changes on how to render and publish your content. There are no changes in the content itself. These stylesheets would include:
- All of your output formats (HTML, PDF, WebHelp, and other)
- Contain all of your formatting specs (fonts, layouts, colors, and more)
- Can contain all boilerplate content that must appear in every publication
- Can provide variant formatting specs for different contexts
Metadata is data about data, more specifically about what’s in your DITA files. It can be broken down to the following:
- Map level – a collection of all of your DITA Files data that’s relevant to inform global search and front matter
- Topic level – the same info as map level, at a lower level, like slight variations, and includes DITA topic types
- Profiling – This allows you to tailor content for specific audiences like conditional formatting
- Subject schemes – This makes sure you stick to exact styles in your content; use to control valid values to use
Warehouse topics are used for smart reuse instead of duplicate copy/paste everywhere
Allows you to organize reusable or swappable content
- By brand
- By product
- By audience
- One identifiable place to go to make global changes
- Can contribute to smart contextual reuse
Keys and keyrefs – helps create a placeholder in the file
- Think of them as variables
- Use indirect (generic) pointers and references in content
- Define the pointers and ref in maps
- Great for swapping out the company name
- Great for differing information
Conrefs and conkeyrefs – if using info from one file in another file, the other file will always be updated
- Conref – smart reuse – uses warehouse topics: Pulls content from one topic into another topic
- Conkeyref – very smart reuse – talks to map files: Based on context, conkeyrefs pull in different content. Indirect addressing and content referencing in one
Before you move to DITA, create templates, standardize your content, and remove formatting overrides. Once you have made your rebranding conversion to DITA, relay solely on stylesheets, address all layouts required for the publication, and ensure that any presentation formats (such as PowerPoint or Keynote) also use stylesheets and named master slides. Make conversion to XML easier by facilitating scripting to convert styles to XML tags, as it’s easier to map a style to XML than formatting patterns. If paragraph and character style names are semantical, it becomes easier to match them against existing XML elements. Overall, remember to remove all formatting overrides!
If writing in Word, start writing and using different formats (like headings) as if you are writing in DITA. It’ll make conversions easier down the road.
And on that note, Adobe DITAWORLD 2019 came to a close. We’re now two-thirds of the way through the conference already! And there’s still more to come!
I look forward to Day 3!