Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Lightweight DITA: A pre/overview

1,337 views

Published on

Presented at the Content Management Strategies/DITA North America conference in 2016; this version is from a repeat of the presentation in webinar form, and includes some additional slides.

Lightweight DITA is being developed at OASIS by a subcommittee of the OASIS DITA Technical Committee. It is designed to make adoption of DITA easier for both users and tool developers. The subcommittee is looking at usage scenarios in areas such as marketing, education, software development, and machine industries.

The goals of the (in-development) specification are:

- simplified topic and map definitions with tighter content models and fewer elements
- simplified specialization process that makes new specializations as easy to create as new topics
- multi-format content, with mappings to not only XML, but also markdown, HTML5, and JSON

Michael Priestley shares the current state of the lightweight DITA specification, focusing on the current draft document types for topic and map, and reviews the lightweight specialization process.

Published in: Technology
  • Be the first to comment

Lightweight DITA: A pre/overview

  1. 1. 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
  2. 2. 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 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.
  3. 3. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 3 Why are we doing this?
  4. 4. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 4 DITA is growing 2012: 250 companies using 2016: 621companies using used with permission, ditawriter/Ixiasoft
  5. 5. 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
  6. 6. 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
  7. 7. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 7 Adapt What DITA does best
  8. 8. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 8 Why should you care?
  9. 9. 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
  10. 10. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 10 Common content Marketing Sales DevelopmentDocumentation Support More content to share • Consolidate • Coordinate • Collaborate
  11. 11. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 11 What if your team is using multiple formats?
  12. 12. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 12 your project your company your content ecosystem Discussion Define “team”
  13. 13. 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
  14. 14. 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?
  15. 15. 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?
  16. 16. 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
  17. 17. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 17 More scenarios
  18. 18. 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
  19. 19. 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
  20. 20. 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
  21. 21. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 21 A minimal content model
  22. 22. 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/
  23. 23. 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
  24. 24. 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
  25. 25. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 25 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
  26. 26. 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
  27. 27. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 27 A minimal collection model
  28. 28. 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/
  29. 29. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 29 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
  30. 30. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 30 A minimal specialization model
  31. 31. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 31 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
  32. 32. 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
  33. 33. 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
  34. 34. 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
  35. 35. 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
  36. 36. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 36 What’s next?
  37. 37. CIO Enterprise Content | ©Copyright IBM Corp. 2014, 2016 37 • 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
  38. 38. 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
  39. 39. 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
  40. 40. Tomorrow’s Presentation Intelligent Content Authoring for Everyone Mike Iantosca, IBM Patrick Baker, Stilo International

×