Lightweight DITA: A pre/overview
-
Upload
michael-priestley -
Category
Technology
-
view
755 -
download
2
Transcript of 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
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 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.
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 3
Why are we doing this?
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 4
DITA is growing
2012: 250 companies using 2016: 621companies using
used with permission, ditawriter/Ixiasoft
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
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 7
Adapt
What DITA does best
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 8
Why should you care?
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 10
Common content
Marketing
Sales
DevelopmentDocumentation
Support
More content to share
• Consolidate
• Coordinate
• Collaborate
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 11
What if your team is using multiple formats?
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 12
your project
your company
your content ecosystem
Discussion
Define “team”
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
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?
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?
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 17
More scenarios
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
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
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 21
A minimal content model
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/
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
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 25
filters
• props attribute
reuse
• conrefattribute
variable-content
• keyrefattribute on ph
variable-links
• keyrefattribute on links
localization
• dir attribute
• xml:langattribute
• translate attribute
Attribute groups
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 27
A minimal collection model
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/
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 29
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 30
A minimal specialization model
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 31
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
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
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
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
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
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 36
What’s next?
CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 37
• 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
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
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
Tomorrow’s Presentation
Intelligent Content Authoring for EveryoneMike Iantosca, IBM Patrick Baker, Stilo International