Lightweight DITA

©2012, 2013 IBM Corporation

Corporate User Technologies

1

Michael PriestleyLead IBM DITA ArchitectTotal Information Experience Technology StrategistSenior Technical Staff Member

Lightweight DITAA preview of the proposed DITA 1.3 feature

April 16, 2013

2

ID Professionals Telecon


Important Disclaimer

THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY.

WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION.

NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, OR SHALL HAVE THE EFFECT OF:

• CREATING ANY WARRANTY OR REPRESENTATION FROM IBM (OR ITS AFFILIATES OR ITS OR THEIR SUPPLIERS AND/OR LICENSORS); OR

• ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF IBM SOFTWARE.

3



Overview

●Background● DITA at OASIS● Lightweight DITA status● DITA across the enterprise● Full vs light

●The proposal● Lightweight topics● Lightweight maps● Lightweight specialization● Out of the box: building blocks and starter types

4



What is DITA?Darwin Information Typing Architecture is an XML standard for modular content, collections and classification that allows an enterprise to:

Keep many versions of content current across multiple audiences, multiple media, multiple deliverables, multiple translations across many geographies

Deliver improved information quality through structured and reused content

Experience faster response time when content for custom products is needed

Leverage traceability and accountability features when a problem is found (fix it once, fix it everywhere; inform other affected authors)

DITA has the largest membership of any OASIS technical committee

Who uses it (selected from http://www.ditawriter.com/companies-using-dita/ )● Accounting● Automotive ● Aerospace● Biotech● Computer

hardware/software/networking● Consumer electronics● Consumer goods● E-learning/education● Manufacturing● Entertainment● Financial services● Health and wellness● Hospital and healthcare● Industrial automation● IT services● Insurance● Management consulting● Medical devices● Oil and energy● Pharmaceuticals● Publishing ● Retail● Semiconductors● Telecom

Who uses it (selected from http://www.ditawriter.com/companies-using-dita/ )● Accounting● Automotive ● Aerospace● Biotech● Computer

hardware/software/networking● Consumer electronics● Consumer goods● E-learning/education● Manufacturing● Entertainment● Financial services● Health and wellness● Hospital and healthcare● Industrial automation● IT services● Insurance● Management consulting● Medical devices● Oil and energy● Pharmaceuticals● Publishing ● Retail● Semiconductors● Telecom

IBM contributed DITA to the OASIS standards organization in March of 2004, where it is now managed by the OASIS DITA Technical Committee.

IBM contributed DITA to the OASIS standards organization in March of 2004, where it is now managed by the OASIS DITA Technical Committee.

http://www.ditawriter.com/companies-using-dita/






http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita




5



Lightweight DITA

● Requirements from community for lightweight version of DITA to ease adoption by groups who don't need all the features of full DITA

● Currently part of DITA 1.3 development, although some discussion of splitting off

● Many solutions already implementing lightweight versions of DITA, but lots of variability – different authoring communities want different subsets

● Standard should provide a lightweight starting point and be easy to extend – alternative to starting with full DITA and subsetting

Everything that follows is a work in progress – it's not normative, and it's likely to change

6



Some scenarios to consider

● Contribution – SME (developer, customer, etc.) creating content to be used by a full DITA system

● Collaboration – SME maintaining content that is used by a full DITA system

● Parallel adoption – authoring team with need for lightweight DITA can share CMS, publishing capabilities with full DITA team

● New adoption – authoring team in a company with no existing DITA usage can start with lightweight DITA and then evolve to full DITA where it makes sense

7



Across the enterprise

Manage

Publish

Author

Manage

Publish

Author

Manage

Publish

Author

Today: Silos inhibitreuse of contentand infrastructure.Content delivery reflects company organization, not customer needs

Manage

Publish

Author

Manage

Publish

AuthorAuthor

content

Tomorrow: Authoring with common standards allows sharing of content and consolidation of infrastructure. Content delivery can be organized around customer needs, not organizational boundaries

Taxonomy

8



Lightweight DITA vs full DITA

Full DITA Lightweight DITA

Topics 94 elements 27 elements

Maps 10 elements(+30 shared with topic

2 elements(+2 shared with topic)

Specialization Structural: any element starting with topicDomain: any element except topicAttributes: @props or @baseConstraints: following constraint model

Structural: topic and body onlyDomain: section and ph onlyAttributes: @props onlyConstraints: predefined

Out of the box 23 document types (for basic, bookmap, learning, machine industry, technical content, subject schemes)

~15 (basic topics and maps, specialization authoring, basic DITA types, basic Information Mapping types)

Building blocks

37 structural and domain specialization modules

To be determined

9



Interoperability between lightweight and full DITA

● Lightweight DITA is a valid implementation of DITA – it is a subset of full DITA

● If a tool supports full DITA 1.3, it should support lightweight DITA 1.3 as well

● To simplify the schema architecture, lightweight DITA uses its own set of DTD/XSD files instead of reusing the (larger and more complex) full DITA set

● Lightweight DITA content should be convertible to full DITA simply by changing the doctype line to point to an equivalent full DITA doctype

● Lightweight DITA and full DITA topics should be able to reuse from each other via conref with relaxed constraints in DITA 1.3

10



A deeper look

● Topics

● Maps

● Specialization

● Out of the box

Again, this is all work in progress – the examples are intended to be suggestive, not normative

11



Simplified topic

● Eliminate advanced features● No prolog metadata or related links

● Eliminate redundant markup● No CALS table (simpletable only)

● Simplify content models● No mixed content: the only place to author

text is in a , and doesn't contain lists or other block-level content

● Predefined constraints to:● Get rid of sections or get rid of content

outside of sections● Limit lists to one level

● Attributes added as functional groups:● “block-level reuse” adds @id and @conref

to , <ul>, <li> etc.● “phrase-level variables” adds @keyref to

<ph>

<topic id="mini" domains="(lwdita-c)(no-nesting-c) (no-sections-c)"> <title>Mini topic</title> <body> This topic has constraints that disallow sections and list nesting. None of the optional attribute groups have been included, so no conditional processing, no conref, etc. <ul> <li>Everything you write goes inside a paragraph.</li> <li>You can add paragraphs, tables, lists, and media.</li> </ul> </body> </topic>

12



Simplified map

● Eliminate advanced features● No metadata or reltable

● Simplify content models● Add <title> element to topicref, eliminate

alternatives● Attributes added as functional

groups:● “TOC referencing” adds @href● “Classification/variables” adds @keys● “Link indirection” adds @keyref

<map id="simpleTOCmap" domains="(lwdita-c) (tocref-c)"> <title>Mini TOC map</title> <topicref href=”mini.dita”> <title>Mini topic</title> <topicref href=”another.dita”> <title>Another topic</title> </topicref></map>

<map id="simplevarmap" domains="(lwdita-c) (taxo-c)"> <title>Mini variable map</title> <topicref keys=”prodname”> <title>My Product</title> <topicref href=”installpath”> <title>[root]/something</title> </topicref></map>

13



Simplified specialization

● Pull together a new specialization out of building blocks● Assemble section types● Add phrases and attributes

● So simple it can be authored instead of coded● Use a specialized authoring topic● Fill in the fields and generate the

specialization● Generate more than just DTDs

● Schemas, RNG... with lightweight schemas or starter sets for full

● Overrides for publishing transforms and editor prompts

● Even a lightweight authoring prototype for testing

<meeting id="abc123" domains="(lwdita-c)(all-sections-c) (goals-d) (agenda-d) (minutes-d)> <title>Minutes for 2012 July 18<title> <shortdesc>Discussions of editor scenarios and processing expectations.</shortdesc> <meetingbody> <goals>...</goals> <agenda>...</agenda> <minutes>...</minutes> </meetingbody> </meeting>

<specdef id=”meeting”> <title>Meeting specialization</title> <specdefbody> <sectiondef> <dl> <dlentry> <dt>Goals</dt> <dd> <xref href=”goals.dita”/> Fill the goals of the meeting </dd> </dlentry> ......

14



Out of the box

● Building blocks● DITA section types such as those used in

task● Information Mapping section types● Some common attribute and phrase

domains● Starter topic types

● DITA concept, task, reference – reassembled to match a valid subset of full DITA

● Information Mapping common topic types● A super-lightweight simple topic● A specialization definition type

● Starter map types● Navigation map● Classification/variable map

<task id="mini" domains="(lwdita-c) (all-sections-c) (task/prereq)(task/context) (task/steps-informal) (task/result) (task/example)(task/postreq)"> <title>Do something</title> <shortdesc>It's better than nothing</shortdesc> <taskbody> <prereq>...</prereq> <context>...</context> <steps-informal> <ol> <li>Do this first</li> <li>Do this second</li> </ol> </steps-informal> <result>...</result> .... </taskbody></task>

15



Review: why lightweight DITA?

● DITA can make it easier to share content and infrastructure across the enterprise

● But full DITA can have a high learning curve that pays off with high functionality only for full-time professional authors

● By clearly defining a lightweight DITA adoption point, we make it easier for new groups to adopt DITA with occasional, contributing, or just lighter weight authoring needs

● And we also make it easier for vendors who specialize in a particular area to add DITA support that suits the needs of their customers without the overhead of supporting the full DITA spec

● Full DITA and lightweight DITA are meant to play together to meet a broad spectrum of authoring and publishing needs across the enterprise

16



Join the discussion

● Lightweight DITA discussion groups at yahoogroups and linkedin

● Blogged about it here:● http://dita.xml.org/blog/lightweight-dita

● Birds of a Feather at lunch table 25

http://dita.xml.org/blog/lightweight-dita

http://dita.xml.org/blog/lightweight-dita

17



Questions

18



Legal

IBM and the IBM logo are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml

19



Appendix

20



Topic content

● Minimal elements (27 total)● Eliminated redundancy● Simplified content models (no mixing and <ph>)

● Core structure: topic, title, shortdesc, body, section● Blocks: p, ul, ol, dl, pre, simpletable, image, object, note● Phrase-level: ph, xref, image

● Modified by predefined constraints● no-nesting: lists are limited to one level● no-sections: body element contains blocks only, no sections● all-sections: body element contains sections only, no blocks

● What's missing?● Metadata elements. Use attributes if you need metadata.● Full table support. If you need the CALS model, you'll need to extend beyond simple

DITA, or go to full DITA.● Related links. You can use a section with xrefs, or use map-based linking. ... to do

21



Topic attributes

● Core required (21; or 7, excluding object and param)● every element: @class● topic: @id, @domains● xref, image: @href, @scope, @format● object: @declare, @classid, @codebase, @data, @type, @codetype, @archive,

@standby, @height, @width, @usemap, @name, @tabindex● param: @name, @value, @valuetype, @type● note: @type

● Controlled via domains organized by function (adding another 5)● Conditional content: @props on section, p, ul, ol, li, dl, dlentry, pre, simpletable,

strow, image, object, note● Content reuse: @id/@conref on section, p, ul, ol, li, dl, dlentry, pre, simpletable,

strow, image, object, note● Variable links: @keyref on xref● Variable content: @keyref on ph, image● Class extension: @outputclass on everything

22



Simplified map

● Minimal elements – most of the work done by attributes

● Only four elements:● map● title● ph (in title)● topicref

23



Map attribute model

● Core attributes (3):● every element: @class● map: @id, @domains

● Other attributes grouped into optional domains by function● Referencing content: @href on topicref● Variable and metadata control: @keys on topicref● Conditional content: @props on map, topicref● Content reuse: @id/@conref on topicref● Variable text: @keyref on ph● Variable links: @keyref on topicref● Class extension: @outputclass on everything

24



Specialization model

● In lightweight DITA, you start with a set of building blocks:● specialized sections for organizing block-level content● specialized phrases for adding semantics to phrase-level content● specialized attributes for supporting conditional processing

● Each new topic specialization:● Defines new topic/body elements● Sequences a set of specialized sections to provide structure● Incorporate phrase-level and attribute domains

● If you need new specializations of section, ph, or the @props attribute:● You define them separately, so they can be reused by multiple specializations● And then incorporate them into your topic specialization

● If you need new block-level specializations (eg a new type of table):● You can do it, you're just going beyond the basics of lightweight DITA

25



Authoring a specialization

● Creating a new specialization should be as simple as filling in a form● No coding or special skills required

● Outputs could include:● Generated DTD and XSD artifacts that allow the new specialization to be validated● “Full-DITA” DTD and XSD equivalents if someone wants to use this approach to

create starter doctypes for full DITA● Output overrides for generated section titles● An authoring prototype – such as an HTML5-based form/editor

● When someone wants to share content authored using the new specialization:● They could bundle the generated artifacts (DTD, XSD, output overrides) along with

the content● Or they could just share the authored specialization topic itself – allowing the reuser

to generate XSD or DTD schemas as they prefer, and potentially generate their own output overrides.

26



Out of the box

● Basic topic types:● Lightweight topic● Super-lightweight topic● Specialization authoring topic

● Basic map types● URI-based TOC map (@href)● Classification/variable map (@keys)● Key-based TOC map (@keys, @keyref, @href)

● Basic DITA types● Concept● Task● Reference

● Basic Information Mapping types (topics built up out of IM blocks)● TBD

27



The building blocks

● Harvest existing building blocks from full DITA so existing semantics can be reused

● Section-level specializations● example (from topic) (technically not a section specialization)● prereq, context, steps-informal, result, postreq (from task)● refsyn (from reference)● prelreqs, closereqs (from learning domain)

● Phrase-level specializations● still to do

● Attribute “specializations”● product, platform, audience (from topic) (technically not specializations of props)

● Coming soon: ● Section types based on the Information Mapping information types