1. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 1
Lightweight DITA
A pre/overview
Michael Priestley, Enterprise Content Technology Strategist
@ditaguy
Content owners: Michael Priestley, Lu Ai, Carlos Evia

2. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 2
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. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 3
Why are we doing this?

4. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 4
DITA is growing
2012: 250 companies using 2016: 621companies using
used with permission, ditawriter/Ixiasoft

5. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 5
• Too many tags
• Too hard to customize
• Steep learning curve
Perceived complexity
• Software developers mostly used XML for data
• So when they switched to JSON, they decided XML was dead
• Bias against XML in favor of Markdown, HTML, or custom formats
It’s XML
But facing adoption challenges

6. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 6
Simplify the
model
No longer
reliant on XML
semantics
Cross-format
content
standard
If we simplify, we can grow beyond XML

7. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 7
Adapt
What DITA does best

8. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 8
Why should you care?

9. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 9
My
tools
Create
Manage
TranslatePublish
Measure
More tools in your ecosystem
• More options to start
• More ways to connect
• More ways to grow

10. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 10
Common
content
Marketing
Sales
DevelopmentDocumentation
Support
More content to share
• Consolidate
• Coordinate
• Collaborate

11. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 11
What if your team is using multiple formats?

12. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 12
your project
your company
your content
ecosystem
Discussion
Define “team”

13. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 13
Developers Writing specs In Markdown
Published to
website,
product spec
sheet
Marketers Writing
overviews
In a web
CMS/HTML5
Published to
website,
product
brochure
Technical
writers
Writing
procedures
In an XML
editor
Published to
website,
product docs
Let’s say this is your team
Remote Lighting Network

14. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 14
Do your own
thing
Each group has its own
authoring tools and
website
Share content by copy
and paste
Let google pick the
winner!
Do somebody
else’s thing
Pick a winner yourself –
one authoring tool, one
website
Drink the salty tears of
the authors in the other
two groups
Or we could
work together
Authors have their
choice of tool and format
Delivery channels are
coordinated and
differentiated
Everyone’s a winner!
What are our options?

15. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 15
Flexibility
• What if developer
takes over some
tasks?
• What if technical writer
takes over some
marketing pages?
• What if task pages
move into the web
CMS?
Coordination
• Share content across
collections with
topicref
• Coordinate variables
with keyref
• (To be built) common
metadata, filtering,
conref
Scope
• What if tasks need to
be published into
support knowledge
base?
• What if overviews and
product details need to
be pulled into RFPs?
• What if tasks and
overviews need to
become embedded
instructions?
What does a standard buy?

16. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 16
Multi-format, reuse flow enabled by cross-format standards
HTML
Remote Network
Lighting
XML
<ph
keyref="product-
name"/>
Markdown
[product-name]
Output to HTML5, PDF,
EPub, and more
DITA Map
<topicref
format=“html”/>
<topicref
format=“markdown”/>
<topicref
format=“dita”/>
https://github.com/VT-CHCI/mixedlightweightdita
Chart from Jenifer Schlotfeldt, IBM
Sample files from Carlos Evia, Virginia Tech

17. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 17
More scenarios

18. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 18
• Example: Product overviews
• Need structure, rich metadata
• Cross-silo: often duplicated in other silos, such as training, tech
docs; opportunity for consolidation
• http://markmail.org/message/tuyyncuow6v2cpzz
Marketing

19. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 19
• Example: Assessment topics
• Need simple structure, personalization and customization
• Cross-silo: Can reuse assessment logic in conjunction with
other assets
• http://markmail.org/message/myrlcflln6g6riui
Training

20. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 20
• Example: API documentation
• Need predictable structure, sometimes metadata and
personalization/variables
• Cross-silo: Can be pulled into developer site, integrated with
product help, packaged as part of code tutorial
• http://markmail.org/message/gz6fup2xmesynkxa
Software development

21. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 21
A minimal content model

22. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 22
title
(text or inline
elements)
shortdesc
(text or inline
elements)
prolog
data (any
number)
body
(block
elements)
section (any
number)
• (block elements)
Topic structure
https://tools.oasis-open.org/version-control/svn/dita/trunk/subcommittees/LightweightDITA/org.oasis.lwdita/dtd/

23. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 23
body contains blocks
followed by sections
sections contain one
optional title followed
by blocks
inline elements and
text only in title,
shortdesc, p, etc. –
never mixed with
blocks
Tightened content models

24. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 24
Bonus: easy conref from one paragraph to another
Topic A
I’m a short, pithy topic
Most of my content is in lists:
• Each item explains something useful
• Sometimes it’s useful elsewhere too
Topic B
I’m a longer, wordy topic
My content is in paragraphs.
Topic C
I’m just a big table full of cells
lots of cells so many cells

25. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 25
filters
• props
attribute
reuse
• conref
attribute
variable-
content
• keyref
attribute on
ph
variable-links
• keyref
attribute on
links
localization
• dir attribute
• xml:lang
attribute
• translate
attribute
Attribute groups

26. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 26
Block elements
• p
• ul
• ol
• dl
• pre
• audio
• video
• simpletable
• fig
• fn
• note
Inline elements
• ph
• image
• xref
• data
Blocks and inline elements
Mutually
exclusive lists

27. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 27
A minimal collection model

28. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 28
topicmeta
navtitle
• text or ph (any number)
data (any number)
topicref (any number)
topicmeta
topicref (any
number)
Map structure
https://tools.oasis-open.org/version-control/svn/dita/trunk/subcommittees/LightweightDITA/org.oasis.lwdita/dtd/

29. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 29
filters
• props
attribute
reuse
• conref
attribute
variable-
content
• keyref
attribute on
content
variable-links
• keyref
attribute on
links
localization
• dir attribute
• xml:lang
attribute
• translate
attribute
Attribute groups
reference-content
• href attribute
• format attribute
• scope attribute
control-variables
• keys attribute

30. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 30
A minimal specialization model

31. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 31
Create an
instance of of
parent type
Annotate the
instance to
define model
Generate lots
of stuff
Reuse across
specializations
with conref
Template-based specialization
http://markmail.org/message/pd4u5kfg44xp5x5c

32. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 32
outputclass attribute
• the intended
element name
specmodel attribute
• define a sequence
• define a choice
group
• don’t define
anything and the
content model
should be the same
as the current
(unspecialized)
element
importance attribute
• whether the
element is required
or optional in its
current context
• defaults to required
in a sequence,
optional in a choice
group
Structural specialization annotations

33. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 33
specmeta element
data or ph or specatt elements
(any number)
data and ph can be annotated
(with outputclass etc.) to define
domain specializations
specatt element
defines specializations of the
props attribute
Attribute and domain specialization annotations

34. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 34
spec role attribute
• whether the content of an element is intended to be generated
by the transform, editable by the author, an editor prompt,
documentation, or used for content modeling purposes only (or
any mix of the above)
• if unset, element content is editable by author (part of template)
Single-sourcing

35. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 35
Example
<topic id=“xyz” outputclass=“meeting-notes”>
<prolog>
<specmeta
conref=“domains/dates.dita#dm/dates”/>
</prolog>
<body outputclass=“meeting-notes-body”>
<section outputclass=“todos”
specmodel=“sequence”>
<title specrole=“generated”>To dos</title>
<p specrole=“doc”>Use the todos element
to organize a list of things you need to do</p>
<ul>
<li>Here’s an example todo</li>
</ul>
</section>
Schema
Processing
override
Docs
Reuse of a
domain

36. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 36
What’s next?

37. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 37
• Discuss what you learn in our LinkedIn group
o https://www.linkedin.com/groups/4943862
• Join the OASIS Lightweight DITA subcommittee
o https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-lightweight-dita
• Contribute to the new Lightweight DITA Open Repository
o https://github.com/oasis-open/dita-lightweight
• Check out Lightweight DITA support in the DITA Open Toolkit
o Markdown support: https://github.com/jelovirt/dita-ot-markdown
o HTML support: https://github.com/jelovirt/com.elovirta.dita.html
o If you like what you see there or use the DITA-OT, support the developer, Jarno
Elovirta
o Donation links on the plugin pages
Beyond the webinar

38. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 38
• Joe Storbeck, Jana
• Keith Schengili-Roberts, Ixiasoft
• Kris Eberlein, Eberlein Consulting
• Mark Giffin
• Mark Poston, Mekon
• Michael Priestley, IBM
• Noz Urbina
• Rahel Bailie
• Rob Hanna, Precision Content
• Scott Hudson, Boeing
• Sissi Closs
• Tim Grantham
• Tom Comerford
• Tom Magliery, JustSystems
Thanks to the members of the Lightweight DITA SC
• Aaron Rothschild
• Amber Swope
• Birgit Strackenbrock
• Bryan Schnabel
• Carlos Evia, Virginia Tech
• Don Day
• Edwina Lui, Kaplan Publishing
• Fredrik Geers, SDL
• Ian Balanza-Davis
• Jan Benedictus, Fonto Group BV
• Jang Graat
• Jim Tivy, Bluestream
• Joe Pairman, Mekon
• John Hunt, IBM

39. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 39
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

40. Tomorrow’s Presentation
Intelligent Content Authoring for Everyone
Mike Iantosca, IBM
Patrick Baker, Stilo International