building an xml publishing system with dita

© 1999-2007 Dakota Systems, Inc. www.dakota-systems.net

1

DocTrain East 2007DocTrain East 2007October 20 – 8:30 AM October 20 – 8:30 AM

Brian BuehlingBrian BuehlingDakota Systems, Inc.Dakota Systems, [email protected]@dakota-systems.net

Building An XML Publishing System Building An XML Publishing System With DITAWith DITA


2

Presentation GoalsPresentation 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


3

AcknowledgementsAcknowledgements

• 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


6

DITA-based ECM ArchitectureDITA-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


7

Business Requirements for DITABusiness 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


High, XML editors are strong advocates

High, Word users are strong advocates

Satisfaction

Medium, but should be customized

LowErrors

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 EditorFrameCriteria

DITA Editors Vs. Frame


9

Characteristics of an Enterprise CMSCharacteristics 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


Goals: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:Goals:- Expand system to Expand system to publish custom versions publish custom versions of content for different of content for different audiencesaudiences

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

- Integrate system with Integrate system with XML content modelXML 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

Evolution of Multi-Channel Publishing Projects


Reuse (multi-level) Repurposing

Reduces content creation costs

Reduces content maintenance costs

Reduces content translation costs

Increases content accuracy

Content Reuse


Profiled Documents

Dynamic Assembly

More relevant info to customers

Easier creation of new products

Fresher, real-time information

Information on demand

Dynamic Content Assembly


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%

Also supports additional language (French) and Additional Output (Wireless)

DITA Publishing Cost Savings


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%

Publishing Time Savings

95%

Translation Savings

30%

Reduced Content Maintenance

20X

Business ROI


Scenario I:

Conference Material


16

Business Requirements 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


17

Website RequirementsWebsite Requirements


18

Print Brochure RequirementsPrint Brochure Requirements


19

Format Neutral View (XML)Format Neutral View (XML)


20

Format Neutral View (XML)Format Neutral View (XML)


21

Adobe InDesign View (XML)Adobe InDesign View (XML)


Scenario II:

Customer Support


23

MOT Taxonomy / MetadataMOT Taxonomy / Metadata


24

MOT Dynamic Content AssemblyMOT Dynamic Content Assembly

• New users click Register button.

• Returning users sign in with Core ID and Password.


25


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


26


• Metadata tags from the Epic Editor Content Classification screen.


27


1. Search “hits” appear in right pane.

2. Desired data can be moved to left pane for publishing.


28


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

• Additional searches can be performed additively.


29


• 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.


30


• 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


32

Common MisperceptionsCommon Misperceptions

My job responsibilitie

s 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…


33

Project Project LifeLife Cycle for DITA Implementations Cycle for DITA Implementations

Goals:Goals:

-Implement System Requirements

-Execute Formal Test Plan

-Involve Users & Stake Holders

-Convert Production Data

Development

Goals:Goals:

-Finalize Requirements Finalize Requirements & System Design& System Design

-Determine Evaluation Determine Evaluation MetricsMetrics

-Pick Low Hanging Pick Low Hanging FruitFruit

-Solidify Project TeamSolidify Project Team

-Train Project LeadersTrain 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


34

Concept: Business JustificationConcept: Business Justification

IT Architects

End Users

Executive Mgrs.

Reduce

Resistance

ROI CalculationROI Calculation

Cost SavingsCost Savings

New RevenueNew Revenue

Competitive EdgeCompetitive Edge

Identify

Opportunity

Inefficiencies

Legal Compliance

Competition

Create

Urgency

Drive

Action

Proof of Concept

Phased Approach

Training


35

Concept: Creating UrgencyConcept: 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”


36


Manager Response:

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


37


“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%”


38


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!”


39

• 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



40


IT Architects

End Users

Executive Mgrs.

Reduce

Resistance





Identify

Opportunity

Inefficiencies

Legal Compliance

Competition

Create

Urgency

Drive

Action

Proof of Concept

Phased Approach

Training


41

Concept: Identifying OpportunitiesConcept: Identifying Opportunities

• Reduce internal publishing costs• Automate production tasks• Streamline editorial processes• Reduce errors• Electronic distribution• Long term support • Internal training


42

• Faster time to market• Premium support revenue • New information products• Document derivation products• New distribution channels

Concept: Identifying OpportunitiesConcept: Identifying Opportunities


43


IT Architects

End Users

Executive Mgrs.

Reduce

Resistance





Identify

Opportunity

Inefficiencies

Legal Compliance

Competition

Create

Urgency

Drive

Action

Proof of Concept

Phased Approach

Training


44

Concept: Reducing ResistanceConcept: 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


45


IT Architects

End Users

Executive Mgrs.

Reduce

Resistance





Identify

Opportunity

Inefficiencies

Legal Compliance

Competition

Create

Urgency

Drive

Action

Proof of Concept

Phased Approach

Training


46

Concept: Driving ActionConcept: Driving Action

• Focus on getting something started • DITA training• Phased approach


47

Project Life Cycle for DITA ImplementationsProject Life Cycle for DITA Implementations

Goals:Goals:






Pilot

Goals:


-Secure Funding


-Qualify Vendors

Concept


48

Pilot: GoalsPilot: 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


49

Pilot: Understand the User ExperiencePilot: 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…


50


Goals:Goals:





Development

Goals:Goals:






Pilot

Goals:


-Secure Funding


-Qualify Vendors

Concept


51

Development: Low Level DesignDevelopment: Low Level Design

• Don’t map inefficient processes to new system

• Address organizational impacts

• Focus on document analysis first

• Use formal approach to usability


52


Goals:Goals:





Development

Goals:Goals:






Pilot

Goals:


-Secure Funding


-Qualify Vendors

Concept Deployment

Goals:





53

Common MisperceptionsCommon Misperceptions

My job responsibilitie

s 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…


54

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.


55

Project Project LifeLife Cycle for Implementations Cycle for Implementations

Goals:Goals:





Development

Goals:Goals:






Pilot

Goals:


-Secure Funding


-Qualify Vendors

Concept Deployment

Goals:





56

Project Killer – CFOProject 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.


57

Common ROI ErrorsCommon 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


58

Project Killer – CMS VendorProject 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.


59

Project Killer – Standards ArchitectProject 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.


60

Project Killer – CMS ConsultantProject 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.


61

Project Killer – Internal IT GuyProject 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.


62

Project Killer – Senior Tech WriterProject 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.


63

Top 10 DITA Project PitfallsTop 10 DITA Project Pitfalls

10. Underestimating data conversion

9. Assuming user acceptance

8. Limiting organizational impacts

7. Automating current inefficient processes


64

Top 10 DITA Project Pitfalls Top 10 DITA Project Pitfalls

6. Giving in to short-term approaches

5. Not recognizing vendor bias

4. Falling prey to IT zealots

3. Over-specializing


65

Top 10 DITA Project Pitfalls Top 10 DITA Project Pitfalls

2. Under-specializing

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


XML Basics


XML ExampleXML Example


69

DITA Topic ExampleDITA 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>


70

DITA Map ExampleDITA 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 IKey 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 IIKey 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 MapsDITA 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 SpecializationDITA 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 SyntaxDTD Syntax

Schema SyntaxSchema Syntax

XPath: Document Model ExampleXPath: 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 AxesXPath: 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.


81

ConclusionConclusion

• Identify your position in the project life cycle

• Target appropriate goals for each project phase

• Avoid the project killers

• Get something started


82

Thank youThank you

Brian BuehlingBrian BuehlingManaging DirectorManaging Director

[email protected]@dakota-systems.netWork: (888) 834-2152 Work: (888) 834-2152 Mobile: (312) 545-1090Mobile: (312) 545-1090

Dakota Systems, Inc.Dakota Systems, Inc.35 E. Wacker Drive, Suite 151035 E. Wacker Drive, Suite 1510

Chicago, IL 60601Chicago, IL 60601


Questions

&

Answers

building an xml publishing system with dita

Economy & Finance