Building An XML Publishing System With DITA

DocTrain East 2007 October 20 – 8:30 AM Brian Buehling Dakota Systems, Inc. [email_address] Building An XML Publishing System With DITA

Presentation Goals

Discuss each component of the architecture of a DITA-based Publishing System

Introduce a ROI evaluation and implementation process for DITA projects

Explore the technical details of DITA projects

Acknowledgements

Paul Prescod, Member of the OASIS DITA Technical Committee

DITA Open Toolkit User Guide

IBM Technical Briefing on DITA

Dakota Internal DITA Documentation

Dakota Systems Overview

Specializes in content design, development and training for multi-channel delivery (web, print, etc.)

Formed in 1999 as a provider of corporate and commercial publishing solutions

Extensive publishing vendor relationships and technical expertise

Staff consists of experts developing the next generation of publishing technology

The DITA Publishing Problem

DITA Vendors Miss the Mark

XML-based Publishing is a top priority for large organizations and DITA Vendors play a large role, but…

It is designed to primarily address electronic distribution.

Integration is 70%-80% of production cost

DITA solutions not tailored for specific industries

Technology partnerships used to fill gaps … are not integrated solutions

DITA-based ECM Architecture DITA Repository XML Components XML Pipeline XML Authors Subject Matter Experts Outside Contributors Epic, X-Metal Word, Frame XML Conversion DITA Distribution PDA’s Web Sites XSL-FO MS-PPT Slides XSLT Omnimark XSLT XSLT XSLT XPP

Business Requirements for DITA

Distributes documents in multiple formats (print, HTML, XML)‏

Manages large volumes of complex documents

Linked to critical production process (revenue generating)‏

Supports multiple languages

DITA Editors Vs. Frame High, XML editors are strong advocates High, Word users are strong advocates Satisfaction Medium, but should be customized Low Errors Medium, but depends on customization High, depends on user Repeatability High, but not in every situation Medium, but only if customized Efficiency High, but consistently overestimated Low, but consistently underestimated Learning Curve XML Editor Frame Criteria

Characteristics of an Enterprise CMS

Natural application for DITA

Separates content and display properties

Spans multiple functional departments

Integrates multiple vendor technologies

Linked to critical production process

Requires dedicated staff to support

Evolution of Multi-Channel Publishing Projects

Goals:

Content reusable content component instead of documents

Streamline review and workflow tasks

Build a central repository for all content

Manage interim as well as final version of content

Content Management

Goals:

Expand system to publish custom versions of content for different audiences

Enable system to publish to multiple formats (HTML, PDF simultaneously)‏

Integrate system with XML content model

Custom Publishing

Goals:

Real time web updates

Automate formatting processing through plugins, macros and scripts

Utilize existing software and skill sets

Optimize design for aesthetics and usability

Automated Formatting Dynamic Content Assembly

Goals:

Allow users to build custom version of documents

Extend UI for search, preview and publishing

Reuse (multi-level)‏ Repurposing Content Reuse  Reduces content creation costs  Reduces content maintenance costs  Reduces content translation costs  Increases content accuracy

Profiled Documents Dynamic Assembly Dynamic Content Assembly  More relevant info to customers  Easier creation of new products  Fresher, real-time information  Information on demand

Also supports additional language (French) and Additional Output (Wireless)‏ DITA Publishing Cost Savings 15% Create Review/QA Index/TOC Assemble 100% 35% 25% 15% 25% 100% Automate: Index, TOC, PDF w/links, CD-ROM – 50% Review, 95% Index & Assemble 50% Reuse: 50% Create, review 25% Concurrent Process - 40% Elapsed time 15%

Hard results:

Soft results:

Increase information quality

Improve information freshness

Enhance information accuracy

Improve content flexibility

Increase customer satisfaction

Expand customer retention

Authoring Cost Savings 50% Translation Savings 30% Business ROI Publishing Time Savings 95% Reduced Content Maintenance 20X

Scenario I: Conference Material

Business Requirements

Distributes documents in multiple formats (Flash, PDF, PPT, Web)‏

Manages large volumes of complex documents

Linked to critical production process (revenue generating)‏

Supports multiple languages

Website Requirements

Print Brochure Requirements

Format Neutral View (XML)‏

Adobe InDesign View (XML)‏

Scenario II: Customer Support

MOT Taxonomy / Metadata

MOT Dynamic Content Assembly

New users click Register button.

Returning users sign in with Core ID and Password.

New users register by entering Name, Phone, Job Title, Reason for Access, Core ID, and desired Password.

Metadata tags from the Epic Editor Content Classification screen.

Search “hits” appear in right pane.

Desired data can be moved to left pane for publishing.

Selected data can be reordered “up” or “down.”

Additional searches can be performed additively.

Custom Title, Part Number, and Release Date can be added.

Front- and back-matter can be included or excluded.

Output type, PDF, HTML, or XML, can be selected.

User is instructed that he or she will be notified via email when document is assembled.

User is warned that document will be purged from server in seven days.

Implementation Details

Common Misperceptions

My job responsibilities shouldn’t change

It works for our website, so it should be able to handle our print pubs…

Picking the right technology is the most critical part of my job…

We can convert our data into any format with no coding…

Project Life Cycle for DITA Implementations

Goals:

Implement System Requirements

Execute Formal Test Plan

Involve Users & Stake Holders

Convert Production Data

Development

Goals:

Finalize Requirements & System Design

Determine Evaluation Metrics

Pick Low Hanging Fruit

Solidify Project Team

Train Project Leaders

Pilot

Goals:

Develop Business Justification

Secure Funding

Identify Stake Holders

Qualify Vendors

Concept Deployment

Goals:

Roll Out System to Users

Gather Production Metrics

Promote Success / Lessons Learned

Concept: Business Justification IT Architects End Users Executive Mgrs. Reduce Resistance ROI Calculation Cost Savings New Revenue Competitive Edge Identify Opportunity Inefficiencies Legal Compliance Competition Create Urgency Drive Action Proof of Concept Phased Approach Training

Concept: Creating Urgency

“ In conclusion, implementing the proposed XML-based CMS will result in the following benefits:

Content production without programming or design experience.

Consistency of design across publications

Streamlined workflow

Increased content reuse

Automatic composition and web delivery”

Manager Response:

“ Jan’s right. These technical writers do complain a lot.”

“ In conclusion, implementing the proposed XML-based CMS will result in total savings of $250K over 12 months yielding a one year ROI of 50%”

Manager Responses:

“ Hmm…I bet this presenter costs us $125K a year in salary, benefits and overhead…eliminating her position over 2 years….”

“ If this is so great, why didn’t I think of it?”

“ Sure, if your project is successful!”

Regulatory Compliance

Budget Expiration

Translation

Management Support

Competitor Comparison

Pending Litigation

Insurance

No Alternative Solution

Poor Quality / Mistakes in Output

Key Customer Request

Cost savings

Concept: Identifying Opportunities

Reduce internal publishing costs

Automate production tasks

Streamline editorial processes

Reduce errors

Electronic distribution

Long term support

Internal training

Faster time to market

Premium support revenue

New information products

Document derivation products

New distribution channels

Concept: Identifying Opportunities

Concept: Reducing Resistance

Unclear definition of XML technology

XML is not needed (MS-Word, RDB’s, etc.)‏

Underestimating implementation risks

We don’t have the time/expertise to implement something new

The current system doesn’t need fixing

Build vs. buy

Standards wars

Concept: Driving Action

Focus on getting something started

DITA training

Phased approach

Goals:

Pilot

Goals:

Secure Funding

Qualify Vendors

Concept

Pilot: Goals

Solve business problem

Define criteria for success

Highlight risks and limitations

Use actual production documents

Involve eventual end users to finalize requirements

Avoid vendor dominance

Utilize as PR tool

Identify system users

Pilot: Understand the User Experience

There are many users:

A customer who calls support…

A user who refuses to use the web…

A editor who needs training…

A author who does not adopt…

A manager who stops trying…

A technician who makes an mistake…

Goals:

Development

Goals:

Pilot

Goals:

Secure Funding

Qualify Vendors

Concept

Development: Low Level Design

Don’t map inefficient processes to new system

Address organizational impacts

Focus on document analysis first

Use formal approach to usability

Goals:

Development

Goals:

Pilot

Goals:

Secure Funding

Qualify Vendors

Concept Deployment

Goals:

Common Misperceptions

My job responsibilities shouldn’t change

It works for our website, so it should be able to handle our print pubs…

Picking the right technology is the most critical part of my job…

We can convert our data into any format with no coding…

Organizational Impacts Project Manager (Project Manager) Although the characteristics and risks of the DAM project may be new, the internal Project Manager still has the ultimate responsibility for delivery. Typesetter ( Style Designer) The role of page based composition and design in minimized. Emphasis is placed on consistent global styles. Writer ( Content Contributor) Writers must learn new skills to create reusable components that can be published in many contexts. Customer (Micro Publisher) Customers are enabled to publish customized training modules or targeted publications. Web Manager (Delivery Manager) As much of electronic delivery is automated, this role is typically expanded to handle all delivery channels. Systems Architect ( Content Architect) Expertise in systems integration gives way to expertise in content integration. Journal Publisher ( Information Publisher) This shift may wreak political havoc as traditional information flows are changed.

Project Life Cycle for Implementations

Goals:

Development

Goals:

Pilot

Goals:

Secure Funding

Qualify Vendors

Concept Deployment

Goals:

Project Killer – CFO ‘ There is no budget for this project' Risks: * Finance personnel don't have the technology background to fully understand the ROI of CMS's. * Finance personnel have a bias toward preventing any new IT cost expenditures.

Common ROI Errors

Understanding Internal Resource Costs

Handling Productivity Loss

Allocating Cost Appropriately Across Budgets

Timing Submissions with Budget Cycles

Interpreting Fixed Costs

Coordinating ROI Horizon

Targeting Cost Savings AND Revenue Generation

Factoring in Risk

Addressing Perceived Value

Project Killer – CMS Vendor 'That's no problem, our software handles it' Risks: * Vendor incentives to push their products and services will bias their CMS solution recommendations. * Vendors have too little information to propose an optimal solution. * Vendors have too much information regarding your operations to propose the lowest cost solution.

Project Killer – Standards Architect 'It's not on our approved list of vendors' Risks: * IT architecture and support resources won't support the ongoing operations of your CMS initiative. * Internal hardware and network resources will not be available to grow your CMS. * Funding won't be approved without IT architecture consent.

Project Killer – CMS Consultant 'Just follow our 6 step Content Materialization Process and reusable content will materialize' Risks: * Preconceived notions will bias the CMS consultant's view of your project. * Your consultant will overly complicate issues to justify his work. * Business alliances will bias the CMS consultant's technical recommendations.

Project Killer – Internal IT Guy ‘ What about my Open Source MS-Word Plugin?!?!’ Risks: * After your implementation, your internal development team won't have the skills needed to support your CMS. * Your internal team might resent an external team of consultants architecting and developing the CMS. * Parallel development efforts might cause confusion.

Project Killer – Senior Tech Writer ‘ Why can’t we round trip with a MS-Word Template?’ Risks: * Writers will place unreasonable technical requirements on the system. * Many of the undocumented workflow and content rules that writers follow will not be built into the CMS. * Writers will complain about the extra burden place upon them to write and tag content. * Writers will complain about the loss of stylistic control that they have over documents.

Top 10 DITA Project Pitfalls

10. Underestimating data conversion

9. Assuming user acceptance

8. Limiting organizational impacts

7. Automating current inefficient processes

6. Giving in to short-term approaches

5. Not recognizing vendor bias

4. Falling prey to IT zealots

3. Over-specializing

2. Under-specializing

1. Assuming that there the business justification for the project will emerge naturally

XML Basics

XML Example

DITA Topic Example Type-specific content body Relationships Identifier and title Properties Type-specific content body Relationships <task id="installstorage"> <title>Installing hard drives</title> <shortdesc>You open the box and insert the drive.</shortdesc> <prolog><metadata> <audience type="administrator"/> <keywords> <indexterm>hard drive</indexterm> <indexterm>disk drive</indexterm> </keywords> <prodinfo> <prodname>TeraDisk</prodname> <vrmlist><vrm version="2" release="1" modification="1"/></vrmlist> </prodinfo> </metadata></prolog> <taskbody> <prereq>First, purchase the hard drive. To avoid problems, please leave the hard drive in the box for now.</prereq> </taskbody> <related-links> <link href="unscrewcover.dita"/> <link href="insertdrive.dita"/> <link href="replacecover.dita"/> </related-links> </task>

DITA Map Example <map title="Tasks"> <topichead navtitle="Installing" audience="admin"> <topicmeta> <shortdesc>Install products before configuring or using them.</shortdesc> <topicmeta> <topicref href="installstorage.dita"> <topicref href="unscrewcover.dita"/> <topicref href="insertdrive.dita"/> <topicref href="replacecover.dita"/> </topicref> <topicref href="installwebserver.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> <topicref href="installdb.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> </topichead> … </map> A heading doesn’t have to have a topic Title and properties can be assigned in the map A topic can appear multiple times in the hierarchy The map organizes a set of topics in a hierarchy

DITA Basics

Key DITA Concepts I

Topic Orientation

Topic: a unit of information that is meaningful when it stands alone

Maps

Organize a set of topics, typically for different deliverables

Topics DITA maps Deliverables

Key DITA Concepts II

Domains

Collections of elements for a particular subject area, e.g. Typographic, Programming, Software, User interfaces, Utilities

Specialization

Structural: Define new types of information

Domain: Define new markup (elements) that can be used across information types

Content References (“conrefs”)‏

Mechanism for reusing standard text

DITA Maps

Analogous to a document of XML entities

Defines the TOC of an information product

Provides pointers to topics

Can define browse sequences and topic metadata

DITA Specialization

Specialization ensures an orderly evolution of information types

All types and domains derive from <topic> or a descendant of <topic>

All elements in a specialization are mapped back to its parent

Specialization is at least as restrictive as its parent

Applications designed for the parent can be used with a specialization, without modification

DTD / Schema Basics

DTD Syntax

Schema Syntax

XPath: Document Model Example  <?app open?> <a level="0" xmlns:b="urn:b" xmlns="urn:a"> alpha <b:bravo/><charlie/> delta </a> <?app close?>

XPath: Navigation Axes

Thirteen navigation axes:

self (self::node() == .);

child (omitted when abbreviated);

parent (parent::node() ==..);

attribute (abbreviated to @);

namespace;

descendant-or-self (descendant-or-self::node() ==//);

descendant;

ancestor-or-self;

ancestor;

preceding;

preceding-sibling;

following;

following-sibling.

Conclusion

Identify your position in the project life cycle

Target appropriate goals for each project phase

Avoid the project killers

Get something started

Thank you Brian Buehling Managing Director [email_address] Work: (888) 834-2152 Mobile: (312) 545-1090 Dakota Systems, Inc. 35 E. Wacker Drive, Suite 1510 Chicago, IL 60601

Questions & Answers