Lightweight DITA: A pre/overview

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

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.

Why are we doing this?

DITA is growing
2012: 250 companies using 2016: 621companies using
used with permission, ditawriter/Ixiasoft

• 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

Simplify the
model
No longer
reliant on XML
semantics
Cross-format
content
standard
If we simplify, we can grow beyond XML

Adapt
What DITA does best

Why should you care?

My
tools
Create
Manage
TranslatePublish
Measure
More tools in your ecosystem
• More options to start
• More ways to connect
• More ways to grow

Common
content
Marketing
Sales
DevelopmentDocumentation
Support
More content to share
• Consolidate
• Coordinate
• Collaborate

What if your team is using multiple formats?

your project
your company
your content
ecosystem
Discussion
Define “team”

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

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?

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?

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

More scenarios

• 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

• 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

• 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

A minimal content model

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/

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

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

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

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

A minimal collection model

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/

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

A minimal specialization model

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

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

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

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

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

What’s next?

• 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

• 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

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

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

Lightweight DITA: A pre/overview

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (19)

Similaire à Lightweight DITA: A pre/overview

Similaire à Lightweight DITA: A pre/overview (20)

Dernier

Dernier (20)

Lightweight DITA: A pre/overview