Industry-Centered Business Strategies

Industry-Centered Business Strategies Presented by JoAnn Hackos, Bob Beims, Chip Gettinger, and Scott Hudson

Understanding DITA: Its Impact On A Global Business Strategy JoAnn T Hackos, PhD President Comtech Services Inc.

What is DITA?Pronounced Dit-Uh • Darwin:DITA uses the principles of inheritance for specialization • Information Typing: DITA is designed for topic-based technical information based on an information architecture of concept, task, and reference • Architecture: DITA provides the framework for the development of an Information Model

DITA at OASIS • OASIS DITA Technical Committee at OASIS • DITA architecture (including base topic types defined in DTD and schema) contributed to OASIS in 2004 • DITA 1.0 specification formally published by OASIS in 2005 • DITA 1.1 specification now under review • DITA public toolkit available through open source (SourceForge) • Domain specific communities beginning to emerge in semiconductor, telecomm, aerospace, and more

Technical author maintains brand integrity By selecting the best DITA type, I can ensure consistency of content and language and enhance our information branding across information libraries.

What is DITA exactly? • DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways • It is also an architecture for creating new topic types and describing new information domains based on existing types and domains • DITA is not just another tool but an international standard to support structured authoring and reuse in any technical domain

Core design principles of DITA • Topic orientation • Discrete units of information covering a specific subject with a specific intent • Topic granularity • Self-contained topics combine with other topics into information sets • Strong typing • DTDs and schemas guarantee that DITA types follow identical information structures • Specialization • Architecture for extending basic types to new types adapted for a particular use within an information set • Common base class • Top-level "generic" base type provides “fallback” for all types

What are the business opportunities? • Enhanced standards at the source • More opportunities for standardized, consistent content • More consistent branding of content • Customized, branded look-and-feel for OEMs and VARs • More reliable use of translation memory • Better schedules, less chaos at the end • Reduced time and cost of production in multiple languages • Automated topic interrelationships to eliminate hand-coding of references and links • More languages and greater customization for global audiences

The DITA Model • Standard, tested DTD • A set of hierarchical DTDs (or schemas) • Three basic information types based on a generic topic type • A set of elements • Information type specific elements • Generic elements • Map/Book specific elements • Domain specific elements

Core DITA topic types Core topic types specialized from “topic” topic A unit of information which is meaningful when it stands alone. reference concept task Provides background information that users need to know. Provides procedural details such as step-by-step instructions. Provides quick access to facts.

The DITA Model • The DITA Maps to assemble topics for output • Relationship tables so that we can relate topics to one another • Standard metadata attributes and values to select and filter content

The DITA Model • Specializationcapabilities that allow us to create new information types and domain-specific elements to meet unique organizational and industry needs • Processes that automate the production of deliverables in PDF, HTML, Help, Eclipse and others

DITA domains • A DITA domain defines a set of elements associated with a particular subject area or authoring requirement regardless of topic type • Current implemented domains • Programming languages • Software • User interfaces

DITA-OT Contents or purpose ant – Templates for defining what to build css – Styles for displaying XML source files in editors or browsers demo – Experiments or demonstrations of DITA capabilities doc – Documentation for DITA or the Open Toolkit dtd – Document type definitions for the DITA vocabulary lib – Java implementation of advanced processing out – Formatted output (created during processing) resource – Styles and other resources for XHTML and other output samples – Example DITA content for exercising the processing schema – XML Schema definitions for the DITA vocabulary temp – Intermediate files (created during processing) xsl – XSLT files for XHTML and PDF processing DITA Open Toolkit

DITA processing .ditamap .XSLT .DTD.schema .dita .CSS DITA map - specifies the order of the DITA source files for your final output DITA source file - where you author your content pieces Document Type Definition – gives structure and validation to your XML source file Stylesheets - are applied to the XML file to produce a formatted output .ditaval Output File (.html) HTML file - is one of the outputs produced from the XML source file (You can also produce PDF, HTML Help, and more) .ditaval file – specifies what information to include or exclude from your final output using attribute values

DITA Specialization to Streamline Data Interchange The Business Case for a Semiconductor-industry DITA Specialization Effort Bob Beims, Application EngineerFreescale Semiconductor, Inc.

Outline • Are Industry Standards In Place? • Are Problems Solved by Exchange? • Do the Data Models Match Up? • How Will DITA Specializations Help? • How Will We Do It?

Semiconductor Data Domains Served by XML Standards • Customer Information Design • OASIS(DITA) • Human readable • Functional descriptions • Data collected from other domains • IP Logical Design • SPIRIT Consortium(IP-XACT, IEEE P1685) • Machine readable • Register descriptions • Signal descriptions • Product Physical Design • RosettaNet.org(RNTD, IEC6-1360) • Machine readable • Product classifications • Characteristic properties

Lack of common language prevents automated sharing of information GatherReq’ments IP Design SoC Integration Verification Documentation Manufacture DevTool Development Training Dev Web Presence Non-aligned Sequential Flows • Sequential, open-loop, disjointed processes and tool chains • Fragile linkage, opportunities for error throughout • Stagnant Desktop publishing practices: • No time for customer needs analysis or filling in the gaps • Book-level reuse is extremely difficult, forces write/copy many, use each asset only once • The critical activity of creating content is squeezed in at the end • Significant non-value-add effort wasted on format conversion and asset tracking • Result: Massively redundant efforts cause errors, missed deadlines and frustrated customers

Standards Bridge the Streams IP Design Customer Information Development Gather Req SoC Integration Verification DITA Training Dev Manufacture Web Presence RosettaNet IP-XACT DevTool Development XML-aligned Concurrent Flows • Parallel, closed-loop, optimized processes and tool chains • End-to-end linkage, requirements through delivery • Leverages Information Development best practices: • Give customers what they need, not simply what we have • Proven topic-based reuse methodology enables write once, use everywhere • Critical activity of content creation is done throughout • Format conversion and asset tracking is automated through infrastructure platform • Result: More time for value-added Information Development means on-time delivery, delighted customers

Merging The Data Streams c n i g g Memory Map, i o Product Design s Signal Names L e Repository (IP-XACT) P D I XQUERY l a XSLT c n i Electrical s g Manufacturing i y Characteristics s Data h e ( IEC 61360 / P Repository D RNTD ) P Relationship XQUERY I Links XSLT n t n o i e t a m Functional m p Information Descriptions r o XQUERY Assets l o ( DITA , SVG , e f XSLT Repository n v MathML ) I e P D I r t y e n r Information Publication m e e Document Types Scripts & Style Deliverables t Engine o v i n and Layouts Sheet t l ( PDF , HTML ) ( ANT , FOP , s o e ( XSL , ditamap ) Repository u C SAXON ) D C

Example: IP-XACT memoryMaps <?xml version="1.0" encoding="UTF-8"?> <spirit:componentxmlns:spirit="http://www.spiritconsortium.org/XMLSchema/SPIRIT/1.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.spiritconsortium.org/XMLSchema/SPIRIT/1.0"> <spirit:vendor>Spirit</spirit:vendor> <spirit:library>Leon2</spirit:library> <spirit:name>uart</spirit:name> <spirit:version>1.0</spirit:version> <spirit:memoryMaps> <spirit:memoryMap> <spirit:name>ambaAPB</spirit:name> <spirit:addressBlock> <spirit:baseAddress>0</spirit:baseAddress> <spirit:bitOffset spirit:format="long">0</spirit:bitOffset> <spirit:range spirit:format="long">16</spirit:range> <spirit:width spirit:format="long"spirit:id="width">6</spirit:width> <spirit:register> <spirit:name>data</spirit:name> <spirit:addressOffset>0x0</spirit:addressOffset> <spirit:size>32</spirit:size> <spirit:access>read-write</spirit:access> <spirit:description>Data read/write register</spirit:description> </spirit:register> </spirit:addressBlock> </spirit:memoryMap> </spirit:memoryMaps> </spirit:component>

Example: DITA memoryMaps 1 • How difficult is it to capture SoC information via the standard DITA model? • Screenshot below shows out-of-the-box use of a DITA-aware editor to capture information in a DITA table. Following slide shows the XML output.

<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> <reference id="RegMapRefXmpl"> <title>Register Map Reference Topic Example</title> <shortdesc>This is an example of capturing register information in a standard DITA reference topic.</shortdesc> <refbody> <table> <title>Register Map Title</title> <desc>Register map table description</desc> <tgroup cols="7"> <colspec colname="regName"/> <colspec colname="regOffset"/> <colspec colname="regSize"/> <colspec colname="regAccess"/> <colspec colname="regReset"/> <colspec colname="regDesc"/> <colspec colname="regDimens"/> <thead> <row> <entry>Register Name</entry> <entry>Offset</entry> <entry>Size</entry> <entry>Access</entry> <entry>Reset</entry> <entry>Description</entry> <entry>Dimension</entry> </row> </thead> <tbody> <row> <entry>data</entry> <entry>0x0</entry> <entry>32</entry> <entry>read-write</entry> <entry>0x0</entry> <entry>Data read/write register</entry> <entry/> </row> Example: DITA memoryMaps 2 • SoC information captured using standard DITA table elements, using colspec attribute for semantic information needed by XSLT processing. • Additional prolog metadata could be added to capture product, platform, audience, revision and otherprops, as needed. • The OASIS CALS table model used in DITA allows use of attributes in entry elements for added semantic tagging. • For information that can be represented in tabular format, specialization may not be needed.

Import option: Pre-process IP-XACT and/or RNTD data to DITA: Pro No OT mods needed, preview in DITA editor Con IP-XACT/RNTD transform breaks direct linkage of elements DITA Processing Pipeline Integration Options Link option: Transform IP-XACT and/or RNTD data within pipeline: Pro Direct, real-time links to latest IPXACT/ RNTD assets Con No preview in DITA editor, OT plug-in development needed

How Will Specializations Help? • Guide authors toward more consistent content creation • Enable round-trip exchange with other XML vocabularies • Symantec information typing for output processing • Potential semiconductor-specific information types: • Instruction Set Architecture reference • Memory Map / Register / Bit Field reference • Signal Characteristics reference • Electrical Characteristics reference • Mechanical Specifications reference

Finding the Specialization Fit • Legacy Document Analysis • Identify often-repeated patterns • Are these patterns filled / created from common data sources of other business processes? • If so, is there an applicable open standard for the data source(s)? • If so … single source and merge the streams! • Specialization Targets • Structures • Element Types • Element Attributes

How Will We Do It? • Gap analysis: information type needs versus base DITA types • Select closest match base DITA elements / structures • Define deltas, create specialized content and processing modules

Do We Need To Do It? • DITA components / attributes vs. SoC customer information set deliverables • Are there SoC information types that get lost in ditabase? • Are there SoC vocabularies that can’t be expressed in ditabase? • Is DITA  IP-XACT / RNTD round-trip impossible with ditabase? (Is it needed?) • Are specific semantic keys needed to generate the output customers have come to expect?

Document Engineering Defined “The principles of document engineering seek to find a balance between technology and business, between process and information, between bottom-up and top-down thinking, and between concepts and implementation. Successful document engineerswill do the same.” Robert Glushko and Tim McGrathDocument Engineering

Adoption of DITA inMedical Devices Chip Gettinger VP, Services and Sales Support Astoria Software cgettinger@astoriasoftware.com

DITA Adoption @ Siemens Medical • Goals • Joint authoring based on a common topic centric model • Re-use processes between service and user doc • Integration of different requirements across business units • Integration of supplier documentation • Preconditions • Existing XML content after transform must be usable with content and versioning information • Authoring workflow: means “authoring as usual” • Use existing Astoria CMS system landscape

Advantages of DITA for Siemens Use of common standards XML/DITA based on OASIS standards with backing from global players. Global content Linguistic adaptability for all used terms. System extensibility Reduces costs for training and simplifies the integration of external information. Exchangeability Simplifies exchange and use of technical information. Traceability Flexible designability of info types combined comprehensible Astoria CMS history. Business Unit integration Local optimum can be reached without loss of global optimum. OEM integration Perfect exchange standard enabling easy integration of suppliers. Flexible publishing Allows publication “out-of-the-box” and customization using individual stylesheets. ... DITA is not fixed on specific content, it contains a method for data modeling.

Structure Content Layout DTD Instance Document analyzing structuring modeling selecting transforming publishing research authoring Modeling Authoring Publishing Process Basics

Evolution within the last years ... With adoption of the Astoria CMS and DITA • Innovation cycles dramatically shortened • Dramatically increased volumes, e. g. content, output media, languages, doc types, authors, products, ... • Documentation creation today concurrent with development • # of languages today = 23 • Speeding up translation & localization cycles • Focus on translation costs • Global use of information according to Single Source principle • Integration of OEM documentation • Increasing process requirements

…. to final layout Structured input – output layout • Clear Structure from creation ….

Usage - How does the customer work ? …Unique and Benchmark at Siemens

Content SieMed Fine structure Information classes Orgdata Publishing structure Processes SieMed Authoring Processing content Reuse Publishing DITA Domains Topic types Attributes Maps topic writing/direct import DITA-based processing DITA-reuse with conref DITA-based publishing/direct export DTD Harmonization based on DITA

DITA.dtd Medical.dtd SiemensMed.dtd Supplier_A.dtd GG.dtd CS.dtd HS.dtd DITA Medical Devices Specializations • Blocks of information can be deduced methodically over several levels • Enables development and use of specific DTDs based on a common foundation

DITA topics, maps and graphics are created, versioned and stored in Astoria Authors reference topics and graphics into product deliverables (Maps) Product configs, audience, etc. are managed as part of each topic Authors can search to discover topics from other authors

Topics are edited using the Arbortext XML Editor via the Astoria Bridge.

Using the DITA Open Toolkit, a Topic Map is published and filtered to HTML Help, PDF, Java Help, etc. that is filtered for a specific customer.

Medical Devices DITA Subcommittee • Defining goals and objectives • Siemens Medical specializations to be available in public domain • Faster time for adoption • Adoption of industry best practices • Supplier content interchange and updates

Learning Content Specialization SC Goal: Develop a general top-level design for structured, intent-based authoring of learning content with good learning architecture, following DITA principles and best practices. Scott Hudson, Senior Consultant

Top-level approach and assumptions • Adopt a top-level design for DITA topic-based learning content that is equally informed by the Cisco/Clark learning objects approach and by leading instructional models, and complements the Sharable Content Object Reference Model (SCORM).

Working Assumptions • A learning object consists of: • instructional objects, which provide the structured framework for a learning experience, and • information objects, which provide the source learning content. • DITA topic types provide the meaning and intention to content contained in instructional and information objects, and as such, comprise the basic building blocks for learning objects. • DITA maps arrange dita topic type files into a sequence as learning objects and organize such content for delivery as lessons, modules, and courses. • DITA specialization provides the mechanism for creating learning-based topic types needed for instructional and information object content requirements.

Industry-Centered Business Strategies