1. Corporate User Technologies
Lightweight DITA
A preview of the proposed OASIS DITA profile
November 28, 2013
Michael Priestley
Lead IBM DITA Architect
Total Information Experience Technology Strategist
Senior Technical Staff Member
1
©2012, 2013 IBM Corporation

2. ID Professionals Telecon
Important Disclaimer
THE INFORMATION CONTAINED IN THIS PRESENTATION
PROVIDED FOR INFORMATIONAL PURPOSES ONLY.
IS
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.
2
©2012, 2013 IBM Corporation

3. ID Professionals Telecon
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
Split off from DITA 1.3 development, uses some features of DITA 1.3 for
doctype design but is processing-compatible with DITA 1.2
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
3
©2012, 2013 IBM Corporation

4. ID Professionals Telecon
Some scenarios to consider




4
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
©2012, 2013 IBM Corporation

5. ID Professionals Telecon
Examples of parallel adoption potential within IBM








Product documentation - hardware and software (first adopters of DITA)
Product announcements (already using DITA)
Semiconductor design manuals (already using DITA)
Learning and training content (proofs of concept)
Support content (proof of concept)
Marketing content (proof of concept)
Technical articles and whitepapers (proof of concept)
Internal policies and procedures (proof of concept)
©2012, 2013 IBM Corporation

6. ID Professionals Telecon
Lightweight DITA vs full DITA
Full DITA
Topics
94 elements
27 elements
Maps
10 elements
(+30 shared with topic
2 elements
(+2 shared with topic)
Specializa
tion
Structural: any element starting with
topic
Domain: any element except topic
Attributes: @props or @base
Constraints: following constraint
model
Structural: topic and body only
Domain: section and ph only
Attributes: @props only
Constraints: predefined
Out of the
box
23 document types (for basic,
bookmap, learning, machine
industry, technical content, subject
schemes)
~6 (basic topics and maps,
specialization authoring, basic
DITA types)
Building
blocks
6
Lightweight DITA
37 structural and domain
specialization modules
To be determined
©2012, 2013 IBM Corporation

7. ID Professionals Telecon
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



7
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
©2012, 2013 IBM Corporation

8. ID Professionals Telecon
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
8
©2012, 2013 IBM Corporation

9. ID Professionals Telecon
Simplified topic

Eliminate advanced features


Eliminate redundant markup



Get rid of sections or get rid of content
outside of sections
Limit lists to one level
Attributes managed as functional
groups:


9
No mixed content: the only place to author
text is in a <p>, and <p> doesn't contain
lists or other block-level content
Predefined constraints to:


No CALS table (simpletable only)
Simplify content models


No prolog metadata or related links
“reuse” adds @id and @conref to <p>, <ul>,
<li> etc.
“variable-content” adds @keyref to <ph>
<topic id="mini"
domains="(lwdita-c)(no-nestedtopics-c) (no-nested-blocks-c)">
<title>Mini topic</title>
<body>
<p>This topic has constraints
that disallow nesting topics and
lists.</p>
<p>Additional constraints could
be applied to get rid of attribute sets
based on function, for example
eliminating conref.</p>
<ul>
<li><p>Everything you write
goes inside a paragraph.</p></li>
<li><p>You can add
paragraphs, tables, lists, and
media.</p></li>
</ul>
</body>
</topic>
©2012, 2013 IBM Corporation

10. ID Professionals Telecon
Simplified map

Eliminate advanced features


Simplify content models


No metadata or reltable
Add <title> element to topicref, eliminate
alternatives
Attributes added as functional
groups:

“Classification/variables” adds @keys

10
“TOC referencing” adds @href

“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>
©2012, 2013 IBM Corporation

11. ID Professionals Telecon
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





11
Use a specialized authoring topic
Fill in the fields and generate the
specialization
Generate more than just DTDs

<meeting id="abc123" domains="(lwdita-c)(allsections-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>
Schemas, RNG... with lightweight schemas
or starter sets for full
Overrides for publishing transforms and
editor prompts
Even a lightweight authoring prototype for
testing
<specdef id=”meeting”>
<title>Meeting specialization</title>
<specdefbody>
<sectiondef>
<dl>
<dlentry>
<dt>Goals</dt>
<dd>
<p><xref href=”goals.dita”/></p>
<p>Fill the goals of the meeting</p>
</dd>
</dlentry>
......
©2012, 2013 IBM Corporation

12. ID Professionals Telecon
Out of the box

Building blocks



DITA section types such as those used in
task
Some common attribute and phrase
domains
Starter topic types

DITA concept, task, reference –
reassembled to match a valid subset of full
DITA



A super-lightweight simple topic
A specialization definition type
Starter map types


12
Navigation map
Classification/variable map
<task id=“mytask”
domains="(lwdita-c) (topic task)">
<title>Do something</title>
<shortdesc>It's better than
nothing</shortdesc>
<taskbody>
<prereq><p>...</p></prereq>
<context><p>...</p></context>
<steps-informal>
<ol>
<li>Do this first</li>
<li>Do this second</li>
</ol>
</steps-informal>
<result><p>...</p></result>
....
</taskbody>
</task>
©2012, 2013 IBM Corporation

13. ID Professionals Telecon
Review: why lightweight DITA?





13
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
©2012, 2013 IBM Corporation

14. ID Professionals Telecon
Join the discussion



14
Lightweight DITA discussion groups at yahoogroups and linkedin
Blogged about it here:
http://dita.xml.org/blog/lightweight-dita
©2012, 2013 IBM Corporation

15. ID Professionals Telecon
Questions
15
©2012, 2013 IBM Corporation

16. ID Professionals Telecon
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
16
©2012, 2013 IBM Corporation