Lightweight DITA: A pre/overview

CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 1

Lightweight DITAA pre/overviewMichael 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 INFORMATIONCONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESSOR IMPLIED.

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

IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATEDTO, 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 AFFILIATESOR ITS OR THEIR SUPPLIERS AND/OR LICENSORS); OR

• ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSEAGREEMENT 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

https://github.com/VT-CHCI/mixedlightweightdita


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

http://markmail.org/message/tuyyncuow6v2cpzz


• 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

http://markmail.org/message/myrlcflln6g6riui


• 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

http://markmail.org/message/gz6fup2xmesynkxa


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

• conrefattribute

variable-content

• keyrefattribute on ph

variable-links

• keyrefattribute on links

localization

• dir attribute

• xml:langattribute

• 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




filters

• props attribute

reuse

• conrefattribute

variable-content

• keyrefattribute on content

variable-links

• keyrefattribute on links

localization

• dir attribute

• xml:langattribute

• translate attribute

Attribute groups

reference-content

• href attribute

• format attribute

• scope attribute

control-variables

• keys attribute


A minimal specialization model


Create an instance of ofparent type

Annotate the instance to

define model

Generate lots of stuff

Reuse across specializations

with conref

Template-based specialization

http://markmail.org/message/pd4u5kfg44xp5x5c

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 groupo https://www.linkedin.com/groups/4943862

• Join the OASIS Lightweight DITA subcommitteeo https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-lightweight-dita

• Contribute to the new Lightweight DITA Open Repositoryo https://github.com/oasis-open/dita-lightweight

• Check out Lightweight DITA support in the DITA Open Toolkito Markdown support: https://github.com/jelovirt/dita-ot-markdowno HTML support: https://github.com/jelovirt/com.elovirta.dita.htmlo If you like what you see there or use the DITA-OT, support the developer, Jarno

Elovirtao Donation links on the plugin pages

Beyond the webinar

https://www.linkedin.com/groups/4943862

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

https://github.com/oasis-open/dita-lightweight

https://github.com/jelovirt/dita-ot-markdown

https://github.com/jelovirt/com.elovirta.dita.html


• 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 EveryoneMike Iantosca, IBM Patrick Baker, Stilo International