Cross-format content with Lightweight DITA

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

Cross-format content with Lightweight DITAMichael Priestley, Enterprise Content Technology Strategist, IBM CIO

Jenifer Schlotfeldt, Senior Content Strategist and Designer, IBM Bluemix

Carlos Evia, Director of Technical and Professional Writing, Virginia Tech


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.


What have we covered so far?


• Why Lightweight DITA?o Lower complexity for easier adoptiono Also allows mapping across formatso Which allows easier adoption

• Minimal topico Fewer elementso Simpler content modelso Functional attribute groupings

• Minimal mapo For managing topic collections, variable

text, variable links, metadata/taxonomies

• Minimal specializationo Start with an instance – for example, a

topic or a tasko Annotate to define content modelo Annotate to provide docs and moreo Conref to reuse definitions across

specializations

Lightweight DITA

<!DOCTYPE topic>


oWhy Markdown?

Enable easier collaboration on

documentation in a format familiar to

developers

Minimal tagging learning curve

oYou can do minimal extensions to keep

it simple, but enable key advanced

features of DITA

Standards for accessibility and HTML 5

Headers, Footers

TOC

Content references

Attributes

Working in Markdown


• HDITA is HTML5-based

• Can be used for source format or presentation

• Does not need a DITA Open Toolkit transformation to produce user deliverables

• Is compatible with DITA XML

• Presents a simpler way to author technical content.

Working in HTML (HDITA)


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?


Can they work together?


Multi-format, Reuse flow

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”/>


Demo


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?


What’s next?


• Check out Lightweight DITA support in the DITA Open ToolkitoMarkdown support: https://github.com/jelovirt/dita-ot-markdown

oHTML 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

oDonation links on the plugin pages

• Play with the sample files we used here:o https://github.com/VT-CHCI/mixedlightweightdita

Play with what you saw today

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

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

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


• Check out the vendor demosoSimplyXML, FontoXML, and Oxygen all have lightweight DITA support

• Discuss what you learn in our LinkedIn groupohttps://www.linkedin.com/groups/4943862

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

lightweight-dita

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

See more, do more

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


• 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

Cross-format content with Lightweight DITA

Technology

Transcript of Cross-format content with Lightweight DITA