Using Markdown and Lightweight DITA in a Collaborative Environment

Leigh White and Keith Schengili-Roberts - April 24, 2017

2017
A Bit About Us
Leigh W. White
• Background in Theoretical Linguistics
• In Tech Comm since 1996
• Working with XML since ~ 2001
• Working with DITA since ~ 2007
• At IXIASOFT since 2013
• Author of DITA For Print: A DITA Open
Toolkit Workbook
• Contributor to The Language of
Technical Communication and The
Language of Content Strategy

2017
A Bit About Us
Keith Schengili-Roberts
• Working in Tech Comm since early
1990s
• Working with DITA since 2004 (pre-
DITA 1.0)
• Was IXIASOFT’s first customer (AMD);
working with the firm since 2015
• Chair of OASIS DITA Adoption
Committee, member of LwDITA SC
and DITA TC
• Author of four technical titles,
contributor to forthcoming Current
Practices and Trends in Technical
Communication

2017
What We’ll Cover
•Lightweight DITA (LwDITA) background and development
•Markdown as entry to LwDITA
•One typical Markdown to LwDITA workflow using the
IXIASOFT DITA CMS
• There are many!
• Import/export and round-tripping concerns
•Demo
Let’s get started!

2017
What is LwDITA?
•It is “a slimmed-down version of the Darwin Information
Typing Architecture. It is designed to ease adoption and
implementation of DITA.”
•Currently three different versions:
• XDITA (LwDITA using XML)
• HDITA (LwDITA using HTML5)
• MDITA (LwDITA using Markdown)
•There is no official specification (yet), but there is
considerable info available, enough to start working with it

2017
The Evolution of LwDITA
• First publicly mentioned by
Michael Priestley (a co-founder a
DITA) in a presentation at DITA
Europe 2013
• LwDITA goals:
• Reduce complexity by stripping
down DITA tagset to its essentials
• Design would allow SMEs to more
easily create content
• Ease adoption of DITA learning
curve by new groups
• This is the birth of XDITA

2017
LwDITA and HTML5
•Subsequent blog post
(2014) on dita.xml.org by
Michael Priestley that first
outlined authoring
LwDITA based on HTML5
principles = HDITA
•Outlined parallel structure
for XDITA and HDITA
• This sparked a further idea…
does DITA need to be bound
to XML?

2017
Tagless DITA?
•Carlos Evia first suggested
using Markdown in LwDITA
•Jarno Elovirta devised
DITA-OT plugin for
Markdown
•This idea was presented
fully at DITA NA 2015, with
introduction of the idea of
Markdown-based DITA =
MDITA
Carlos
Jarno

2017
So Where is LwDITA Today?
•Being driven by OASIS Lightweight DITA Sub-committee
•Two draft Committee Notes are currently in
development:
• Authoring Elements: Outlines rationale for LwDITA, describes how
XDITA, HDITA and MDITA “tags” are intended to work
• Template-based Specialization: Separate document outlining how a
simplified, template-based specialization mechanism for LwDITA
ought to work
•Committee Notes != Specification
• …but they will outline the path to be taken

2017
LwDITA vs. “Full” DITA
DITA 1.3 All-inclusive:
DITA 1.3 Base:
Lightweight DITA:
•26 document types, 621
elements
•4 document types, 189
elements
•1 document type, 46
elements

2017
Some General LwDITA Guidance
•LwDITA content is still valid DITA and can be
incorporated into “full” DITA
•No automatic “round-tripping” between DITA and
LwDITA
•Just map, no bookmap
•Mixed content not allowed; all text must be in a <p>
•No CALS table elements (i.e. <table>, <row>, <entry>,
etc.)
•It is really “DITA”, as content is not typed (result is a
generic topic)

2017
LwDITA Bonus: Multimedia Controls!
•Current draft of the Committee
Note includes eight additional
elements, most of which are
focused on multimedia
•None of these elements
currently exist in DITA 1.3 (but
may in DITA 2.0)
•Ability to add multimedia
sound/video content in line
with HTML5
Multimedia:
<audio>
<controls>
<fallback>
<poster>
<source>
<track>
<video>
Also:
<fnref>

2017
How MDITA Aligns with Markdown
•There is no single standard for
Markdown
•Base MDITA is derived from
GitHub-flavored Markdown (GFM)
with tables as an option
•“Valid, extended” MDITA includes
GFM, YAML headers, and HDITA
elements where no equivalent
exists in Markdown
• e.g. <note> becomes <p data-hd-
class="note">
=

2017
Simple GHF MDITA Topic Example
YAML Header
Title
Numbered List
Image
Table

2017
Simple GHF Map Example
YAML Header
Title
Link to Topics

2017
Interest in LwDITA from the DITA Listening Sessions
LwDITA came up many times
during the OASIS DITA
Listening Sessions (hosted by
DITA Adoption):
•Most were interested in
using it to gather information
from SMEs, typically
software developers
•At least two firms were
already using it in production

2017
One Typical Workflow [1]
1. SMEs or developers/engineers author Markdown in a
third-party system
• Could be procedures, troubleshooting, extracted code samples,
error messages, etc.
• Type of information could drive import process and organization
within DITA CMS... decisions to be made!
2. Markdown is converted to LwDITA* outside of CMS
• Currently no way to dynamically convert upon import, but not out of
the question for future
• Could happen in various ways... we will show use of Markdown and
Normalize DITA-OT plugins
*Does not have to be LwDITA per se... we’ll get to that

2017
3. Converted DITA is imported into the DITA CMS
• Can be imported as read-only
• Can be imported to overwrite previously-imported versions of the
same content or to create new content
• Doctypes of imported content can be retained as-is or refactored as
needed

2017
4. Edit imported content as necessary (if not read-only)
5. Add topics to maps as appropriate
6. Reference from topics as conrefs, conkeyrefs, keys,
cross-refs, etc. as appropriate
7. Send content through review/approval cycle as
appropriate
8. Output deliverables
9. Rinse and repeat

2017
Markdown to LwDITA: A Must?
•Converting Markdown to LwDITA is a safeguard against
introducing elements that would not round-trip back to
Markdown
•If roundtripping is not a concern, convert to full DITA
• Possibly a distinction without a difference since Markdown markup
is limited and therefore will be converted to limited DITA tagset
anyway
•You determine whether content is imported into CMS as
full DITA or LwDITA

2017
Third-party System Export Concerns
Can external conversion process guarantee static file
names and IDs from cycle to cycle?
•If file name is dynamic and different from export to
export, the CMS cannot match incoming content to
existing content to overwrite...will create new content
• Existing references will refer to old content, not new content
•If internal IDs are dynamic and different from export to
export, the CMS will overwrite previous IDs with new
ones
• Existing references will be broken
• Import is a simple overwrite, not an intelligent compare/merge

2017
Round-tripping: DITA CMS Concerns
•Upon import, DITA CMS refactors file names to
aaannnnnnnnnnnnn.xml format
• DITA CMS retains original file name in object properties
This is used for content matching in subsequent imports of same
content (and optionally, original file path)
• Content is exported from DITA CMS with refactored file name
Export could be configured to revert to original file names but not
currently part of DITA CMS
•What kind of matching/overwriting can third-party
system do on import?

2017
MDITA a Solution for Easing Content Conversion?
•One other possible scenario for MDITA -> DITA use is
converting text-based content where no other source file
exists
• e.g. have a PDF of a document but no longer have the source file
that produced it
•Can take text from the file, add YAML headers, plus
search-and-replace routines to add MDITA content. Then
use a textfile-splitting program to process the result into
individual MDITA files.
• These files can then be imported into “full” DITA where additional
processing (i.e. content typing, use of full range of DITA elements)
can be done

2017
In summary / Questions
• LwDITA not finalized but far enough along for use
• Collaborative workflow should be one-way, don’t attempt
roundtripping
• Content modeling of imported content is a must
• File names and id's of content exported from third-party system
must remain static
• DITA CMS not concerned with conversion method; only that
resulting content is valid DITA
• DITA CMS does not include dynamic conversion of content upon
import
• Plugins for converting Markdown to DITA are currently available

2017
QA
Blog: www.ixiasoft.com/en/news-and-events/blog
Twitter: @IXIASOFT (plus @KeithIXIASOFT and @LeighWW)
IXIASOFT DITA CMS Users LinkedIn group:
www.linkedin.com/groups?gid=3820030

Using Markdown and Lightweight DITA in a Collaborative Environment

Recommended

More Related Content

What's hot (20)

Similar to Using Markdown and Lightweight DITA in a Collaborative Environment (20)

More from IXIASOFT (19)

Recently uploaded (20)

Using Markdown and Lightweight DITA in a Collaborative Environment