DITA versus DITA-OT

©2017 IBM Corporation
DITA versus DITA-OT!
Who gets the credit?
Who gets the blame?
Robert D. Anderson, IBM
@robander
April 26, 2016

©2017 IBM CorporationDigital Services Group
Agenda
• Why are we here?
• What is the difference between DITA and DITA-OT?
• When and why does it matter (or not)?
• Who do you go to for …
• Updates?
• Fixes?
• Questions?
• Drinks?
• Diagrams!!!!
• Assigning blame!!!!!
(Or credit, you know, whatever.)
2

What I expect you are expecting…
• “DITA” as a solution:
• Is this DITA, is this DITA-OT? Is it something else entirely?
• How do I identify and evaluate the parts?
• How are those parts managed and updated?
• How can you influence that process?
What am I missing?
3
• This is an introductory talk. But it is not:
• An introduction to using DITA
• An introduction to using DITA-OT

What should I expect…?
• In the audience…
• Unfamiliar with DITA?
• Unfamiliar with DITA-OT?
• Lemur fans?
• Already know everything I’m going to say?
• I expect you to ask questions when you have them
4

Why am I the one up here?
1. I’ve been working with the DITA and the toolkit since
The Beginning (of those things)
2. My name shows up on both…
3. …which means I’m part of the problem.
5

Party game: This, That, or the Other
6
✓ Is this DITA (is it the source)?
✓ Is this processed DITA (is it the implementation)?
✓ Is this a solution?
More entertaining version of this game:
http://www.wnyc.org/story/herb-my-little-pony-or-enya-song/

Standalone map or topic: DITA, DITA-OT, or solution?
7

Standalone map or topic: DITA, DITA-OT, or solution?
8
This is raw DITA source.

Docs at dita-ot.org: DITA, DITA-OT, or solution?
9

Docs at dita-ot.org: DITA, DITA-OT, or solution?
10
HTML rendered by DITA-OT from DITA source (Also: DITA-OT docs)

LottaDita JetPack™ Editing, Publishing, CMS, and
translation system: DITA, DITA-OT, or solution?
11

Trick question: DITA, DITA-OT, or solution?
12

Trick question: DITA, DITA-OT, or solution?
13
• This is the DITA
Specification – the very
definition of DITA
• Also: DITA source as
rendered by DITA-OT

Source, implementation, or solution?
14

So what is DITA?
Not software.
It’s a set of rules for everyone to follow:
• What are the valid elements and attributes?
• What’s the syntax for conref?
• How is a key resolved?
Every conforming DITA implementation follows these rules
Grammar files (DTD, XSD, RelaxNG) that enforce rules
15

This is the DITA standard
• What does <shortdesc> mean?
• What is the syntax for @conref?
• What is allowed inside of <topicref>?
• What is the algorithm for resolving @keyref?
16

So what is DITA Open Toolkit?
Open source software …
… intended to publish your DITA content …
… which makes it an implementation of DITA …
… but does not make it DITA …
… even though it is a component of many DITA solutions.
17

This is the DITA Open Toolkit
18

More specifically…
• It’s the software that turns your stuff (usually DITA) …
… into something else (usually not DITA)
19

Why does it matter which is which?
• Because I’ve lost enough hair already.
• And I pull out a little bit more every time my manager asks me to change the
DITA standard to make their PDF look better.
20

Why does it matter to you?
• You want ...
… new functions, new fixes, new options.
• Ask your mechanic for a better satellite radio station …
… when will you get it?
• Tell your cell provider that an app has a bad UI …
… how will that work out?
• Know which part isn’t working …
… and you’re much closer to that part fixed.
21

So who governs DITA?
• The DITA Technical Committee at OASIS owns, develops, and publishes DITA
• Every member of the DITA TC is a member of OASIS (individual or corporate)
• Many members; smaller group of voting members**
22
** background of
voting members is
primarily liberal arts

What kind of changes must go through OASIS?
• Changes in elements or processing rules
• “The world needs a new element for the semantic <chocolate>”
• “I need to put <shortdesc> inside of my <table>”
• “I’d like to propose simplifying the @domains attribute”
• DITA TC members would evaluate and respond to these requests
• “<chocolate> sounds tasty but is best left to specialization”
• “You can already use <desc>, which seems to serve your needs”
• “That sounds wonderful – now somebody needs to work out the details”
23

How to suggest changes…
✓ Become a member of the DITA TC
✓ Get a friendly TC member in your debt
✓ Hire a DITA consultant who is a TC member
✓ Use the OASIS dita-comment email list
✓ Ask your DITA vendor to pursue the idea
(this works much better if they already participate)
24

Where do suggestions go?
• Evaluated weekly by TC.
• To move forward an idea must:
• Be useful
• Have an owner
• Survive several rounds of evaluation
• Remember: these are volunteers. Be kind.
• Implementation target: next major DITA release
25

So who governs DITA-OT?
• Governed by active
participants**
• Anybody can participate
• The more you participate,
the more influence you have
26
** backgrounds are a mix of
language, communication,
and computer science

What kind of changes must go through DITA-OT?
• Changes to how DITA is processed
• Common preprocess fixes or enhancements
• “This one case of my conref to a key in another scope from a
specialized map is not properly setting the @importance attribute”
• “I’d like to suggest an extension to <coderef> resolution that
highlights code syntax”
• Changes to how final rendered content is generated
• “The default DITA-OT HTML5 output should add a ‘tweet this’
button to footers”
• “Who came up with this PDF2 attribute set design, let’s simplify to
make extensions easier”
27

How to suggest changes…
✓ Github pull request
✓ Github issue tracker
✓ Attend contributor calls
✓ Ask your DITA vendor
28

Where do suggestions go?
• Remember: these are either volunteers, or
responsible to their own managers.
You do realize how many nights and weekends
Jarno Elovirta has spent on this, right?
• If there is interest in a fix or enhancement,
any participant may pick it up
• This is open source. If you want something,
participating may be the only way to
ensure an implementation
29

Reminder: DITA / DITA-OT are only 2 components
• Editor may hide complex syntax, set links
without ever displaying <link>
• CMS may enable reuse without ever
introducing the term “conref”
• Browser support could vary for your
custom HTML5 output
• DITA specializations / DITA-OT plugins
can do anything and (almost) everything
30

“I NEED THIS WORKING RIGHT NOW!!!!!!!!!!!!!!!!”
• DITA (source format) issues:
• @outputclass
• Specialization
• Ignore semantics
• DITA-OT (publishing) issues:
• Extend on your own with a plugin
• Hack the code
• Hire Jarno and/or a consultant
• Vendor issues:
• Probably depends on the vendor
31
For any issue: there’s always
dita-users@yahoogroups

Quiz: are DITA and DITA-OT the same?
32
No.
They are not the same.

Quiz: who manages DITA and DITA-OT?
33
They are not managed by the same group of people.
But there is overlap.
I’m a pretty good example of overlap.

DITA CMS
systems
Bonus: SOLUTIONS BUNDLE THINGS!
34
DITA Editors
DITA-OT
DITA
rules
DITA-OT ships and enforces DITA grammar rules
Many (not all) DITA editors bundle DITA-OT, and ship / enforce DITA rules
Many (not all) DITA CMSs bundle DITA-OT, and ship / enforce DITA rules
DITA solutions can bundle some or all of these into a single piece of software

Things that have
“patches”
Bonus: Bugs? What bugs?
35
Things that have
“Errata”
DITA-OTOpen
Standards
Firefox
Phone
apps
Trousers
Textbooks
Wikipedia?
DITA
1.3

DITA: further study
OASIS DITA TC:
https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
OASIS DITA Comment list:
https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=dita
TC Front page (active work):
https://wiki.oasis-open.org/dita/FrontPage
Get involved! Please!
36

DITA-OT: Further study
Monthly DITA-OT Contributor calls: hosted by
Syncro Soft, open to anyone
Monthly DITA-OT Docs calls: hosted by Eberlein
Consulting, open to anyone
Github project: https://github.com/dita-ot/dita-ot/
Everything else at http://dita-ot.org
Get involved! Please!
37

Questions?
38

Super secret DITA-OT shortcut resources!
Maybe these are useful? If so, tell your friends!
If you’d like to keep your friends, just tell your co-workers!
• http://code.dita-ot.org  redirects to http://github.com/dita-ot/dita-ot/
• http://issues.dita-ot.org  redirects to http://github.com/dita-ot/dita-ot/issues/
• http://wiki.dita-ot.org  redirects to http://github.com/dita-ot/dita-ot/wiki
(Used for contributor meeting minutes)
• http://metadita.org/toolkit/  A Puffin’s Guide to DITA*
* My musings on DITA & DITA-OT. I’m not really a puffin.
39

Image credits
Jetpack Image Courtesy NASA/JPL-Caltech
http://www.jpl.nasa.gov/visions-of-the-future/
Old-time images from British Library Flickr stream
www.flickr.com/photos/britishlibrary/
40

Thank you
Digital Services Group

DITA versus DITA-OT

Recommended

Recommended

More Related Content

What's hot

What's hot (9)

Similar to DITA versus DITA-OT

Similar to DITA versus DITA-OT (20)

Recently uploaded

Recently uploaded (20)

DITA versus DITA-OT