Optimal use of XML based content with focus on reuse By Keld Jellesen November 14, 2017

Important historical milestones for XML Keld What is XML - what does it stand for? Extensible Markup Language the lead of XMLs creation was Jon Bosak from Sun. Late 90’ies. What was the predecessor to XML ? SGML (Standard Generalized Markup Language). In 1986 it became an ISO standard. Invented by Charles F. Goldfarb who started the work in mid 70’ies When did SGML take-off and in big scale and under what name HTML by Tim Berners-Lee 1991. HTML is a SGML protocol Two important differences between SGML and XML Omitted end-tags. XML always require-end tags </> XML has a build in presentation framework through XSLT and XSL-FO When did Mr. Jellesen start to work with markup languages professionally as a software programmer 1994 within Aerospace/Aviation through CRI. SGML was adopted by the Aerospace community early 90’ies Works today with XML and JSON as well and primarily two XML standards DITA-XML and S1000D-xml particularly in relation to optimize maintenance 1986-1994 worked in R&D with 3D imaging in relation to nuclaer reactor inspection. Who is big SGML/XML parser developer in the world. Open source programmer idealist James Clark. A rich british child and extremely intelligent. He build his first parser in 1991.

XML (its looks like a database)

XML and Presentation Single XML- Source Single source to multi-publishing output A transformation language XSLT (electronic) and XSL-FO (paper)

Has XML a competitor or a collaborator ? JSON (JavaScript Object Notation). About 10 years old (invented by Dr. Douglas Crockford in 2001) Some consider JSON as a competitor to XML Some consider it as complementary, because it is filling out a space within WEB2.0 as the dynamic piece, which is not that well covered in XML JSON is used as format within what is referred to as document databases advice2u is using JSON in the DIB-mobile solution “we love it”, but we also love XML, and we think they compliments each other perfectly.

Let us focus on reuse and how to author technical data Two standards for doing structured technical authoring S1000D (mechanical structures primarily within aviation) DITA (Software, books, magasins, electronics, etc) Let us focus on DITA for now and not S1000D

What is DITA in brief Is an XML-based architecture for authoring, producing, and delivering information Using Topic based authoring as the paradigm Modular instead of being book-oriented. Moves organizations into minimalistic writing (reduces amount of documentation – examples are 20 % or more) The basic topics in use for the mechanical industry are generic topic, task and concept. Assembly of contents are done through maps ”D” in DITA stands for Darwin – evolution is done through specialization technique found in DITA – easy to make new DOMAINS. DITA contents can easily be distributed to formats like HTML, PDF, Windows Help, Eclipse Help, RTF, and ePUB through the OT (Open toolkit) developed and maintained within the open source community managed through IBM. OT - Nearly used in all working DITA environments. OT makes it easy to start working with DITA because contents can easily be rendered.

Fundamentals for building technical publications Topics (xml) Maps (xml) Publication (xml) Final output User Guide Repair Guide Tech. Spec. Marketing $$ A MAP could also be based upon a query e.g based upon a reference system. Check instructions on a specific functional domain

Unstructured content TASK TASK TASK STEP STEP STEP STEP STEP STEP STEP Just content authored in an unstructured editor Layout and flow managed by author Questions to ask if to move to structured content Does the content have life cycle and will it undertake changes during the complete life cycle ? Is it authored and maintained by one person TASK TASK TASK WARNING WARNING WARNING WARNING WARNING WARNING CAUTION CAUTION WARNING STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP CONDITION CONDITION CONDITION CONDITION

Structured content in XML We see that a lot of content between tasks are common What do we do ? TASK TASK TASK PREREQS PREREQS PREREQS WARNING WARNING WARNING WARNING WARNING WARNING CAUTION CAUTION WARNING STEPS STEPS STEPS STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP CLOSEREQS CLOSEREQS CLOSEREQS CONDITION CONDITION CONDITION CONDITION

Explicit linking of content inclusion It is called CONREFS in daily XML terms Yes XML handles this nicely TASK TASK TASK PREREQS WARNING WARNING WARNING WARNING CAUTION WARNING WARNING WARNING CONREF STEPS STEP CAUTION STEP CAUTION STEP STEP CAUTION STEP STEP STEP NOTICE STEP STEP CONDITION STEP CLOSEREQS CONDITION STEP CONDITION CONDITION STEP CONDITION CONDITION STEP CONDITION

Implicit linking of content inclusions TASK TASK TASK PREREQS WARNING WARNING CAUTION WARNING KEY MAP STEPS KEY STEP KEYREF Fragment file STEP STEP KEY STEP KEYREF CLOSEREQS STEP CONDITION STEP KEY KEYREF CONDITION STEP STEP

Variations through implicit linking TASK TASK Fragment file TASK PREREQS STEP WARNING WARNING STEP CAUTION STEP WARNING STEP KEY MAP KEYREF STEPS STEP KEY STEP KEYREF Fragment file STEP KEYREF STEP KEY STEP KEYREF CLOSEREQS STEP KEYREF STEP KEY CONDITION KEYREF CONDITION STEP KEYREF STEP

Variations through implicit linking How to avoid manual labour work TASK TASK Fragment file Filter TASK PREREQS STEP WARNING WARNING STEP CAUTION STEP WARNING STEP KEY MAP STEPS STEP KEY STEP KEYREF Fragment file STEP KEYREF STEP KEY STEP KEYREF CLOSEREQS STEP KEYREF STEP KEY CONDITION KEYREF CONDITION STEP KEYREF STEP

When thing breaks and it does ! “Make it an excitement” TASK TASK Fragment file Filter TASK PREREQS STEP WARNING WARNING STEP CAUTION STEP WARNING STEP KEY MAP STEPS STEP KEY STEP KEYREF Fragment file STEP KEYREF STEP KEY STEP KEYREF CLOSEREQS STEP KEYREF STEP KEY CONDITION KEYREF CONDITION STEP KEYREF STEP

The biggest challenge how to find stuff to reuse OUTDATED WHERE TO LOOK SLIGHTLY BETTER SOMETHING LIKE THIS ”the lazy” Reference System ”the nerds”

Filtering as a reuse mechnism. ”Only works on final output” TASK TASK TASK WARNING WARNING WARNING WARNING WARNING WARNING CAUTION CAUTION Conditional processing WARNING STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP STEP CONDITION CONDITION CONDITION CONDITION

Challenges in filtering Accuracy in META-data DENMARK Denmark denmark Danmark All 4 danish component are from XMLs point of view not the same I have never seen any organisation been able to handle this problem unless it done by 1 person and the same person. DITA-1.2 has a solution to this problem. Also XML editors may have had their own support for this possibility

DITA solution to handle and control meta-data values DITA solution to handle and control meta-data values. It is called SubjectScheme SUBJECTSCHEME SUBJECTDEF DENMARK Denmark Danmark SUBJECTBIND audience

Other mechanisms for doing reuse in DITA Chunking (on output) Scoped keys (DITA-1.3). More advanced filtering

Other important matters when dealing with XML Two type of people are needed in a successfull XML implementation. Authors who is structured and understand why structure is needed to support the value chain. Engineers/Programmers/XML architects who can automate the value chain. Software needed (The basics) Bacially a good XML editor Oxygen (probably the leader but also expensive) XML-mind a powerfull DITA XML aware editor (a free version is available) Xmetal, Arbortext, etc Notepad++, sublime, etc. Editors of the programmer A lot of open source software is available DITA-OT which is widely used in the DITA world. I think all DITA CMS includes DITA-OT in their package. A CMS is importing to do link management efficiently. But don’t buy it before you understand the basic technology One major lack in XML Graphics is still poorly implemented in XML, but maybe HTML5 adaptation of SVG will change this problem.

Summaries and others Understand the history of XML It is an old technology as an IT technology It is backward compatible and independent of media technology Therefore XML is ideal for content with a long life cycle A powerfull storing mechanism for documentation data XML is a Powerfull Technology It is textual based (means readable on files). Compared to e.g. data in relational databases. So it is easy for non-programmers to evaluate results DITA-XML/DITA-OT is a add-on framework and tool to move quicker on implementations of XML based documentation. DITA-XML is also powerfull in relation to interchange of data Not covered in this presentation. DITA lightweight – HTML5 based. DITA 2.0 will not be backward compatible (>2019/2020)

Presenter contacts Keld Jellesen CEO and Founder. MSc, Bcom advice2u Aps (www.advice2u.dk) Diplomvej 381, 2800 Kongens Lyngby Email: keld.jellesen@advice2u.dk Skype: keld.jellesen Mobile: +45 30-277-965 (30-css-xml)