Using DITA with contextual help #CCMS #mixed-content


Does anyone know of a contextual help application (such as WalkMe) that allows for integration of DITA topics?


We have implemented our own version of this.  Short story...  You can transform DITA topics to JSON, and pass those to bootstrap tours.  We add metadata to the DITA that describes where the given content will attach to the GUI, transform to JSON, and load it on request.

Long Story:
We implemented a system that transforms our DITA on the fly -- you choose the XSLT to pass to it with each request.  So one request is to get a topic and transform it to JSON. 

We have restrictions on the topic that this can work for -- you can't just pass any DITA and expect it to work. You need chunks that are small enough and focused so they can be meaningful in a walk-through tour.  You also need metadata to describe the GUI URL to display and to give CSS selectors that identify the specific GUI item that you are talking about.  Typically I suppose you would use specialization, but we're lazy.  We just know which topics are set up.  We use the procedural list, where each step is another balloon in the tour.  But we also use the same topic in our online help and our PDF.  True single-sourcing.

The tour is implemented using bootstrap.  That's a JS lib for GUI objects and widgets.  It wants an array of JSON, so we transform the procedural list into that.  Our GUI developers implemented it so it can display in the GUI.  When you request a tour, you specify the topic file to load, plus the XSLT for TopicToJson.  Once it's in place, it just works.  I prefer this to using a SaaS hosted by some other party...  You can modify it if you need, and there's no monthly fee.

You could always do the transforms at build time, rather than real-time.  We do real-time for a number of reasons.  One advantage is that we ship the same source for OEM products, or for releases with different feature sets.  We just filter the content appropriately at request time.  All the book-keeping is stored in the source itself, rather than relying on different build switches and storing the output in different repositories, etc.  For us that's way more agile...

Maybe another approach would be to look at something like WalkMe and see if it can import content.  Then just figure out what you need to transform your DITA into so it can import it.  I see that WalkMe does support CSV...

So...  You could possibly transform your DITA to the CSV and load that.  But all this is just speculation.  I have no experience!


Hi Chris,

What is the subset of DITA elements you allow to be in a piece of such micro-content? Bold, italic, lists, images, or just straight text? We also have a requirement to generate JSON output that can be consumed by a web app and rendered by the app itself, using either Metadata seqrch or a brute force unique id mapping for each item in the app UI for which micro-content should be shown.



Hi John...

There are two parts to this transform.  First is the part that generates the JSON array.  This is very much tied to the topic structure...  For these topics we have two sections.  The first section is always for the overview -- We supply it with metadata to open the proper GUI URL, and then we give the content for the first balloon in the walk-through tour. So that is always the first item in the JSON array.  The second section contains the OL that has the procedure steps.  For each step in that OL, we create a subsequent array item, with the GUI mapping, and with the LI content.  The first pgf in the LI becomes the balloon title, and the rest of the LI content becomes straight HTML for the balloon content.

The second part of the transform produces the balloon content.  In principle, this can be anything that can live inside of a LI element.  But...  Since we don't need it, we don't transform everything.  Currently we support ul, ol, p, codeblock, codeph, b, i, and text.  I suppose we could do tables (for example), but they don't make sense in a skinny balloon. 

We don't support graphics -- I'm not sure how the paths to graphics would work in these walk-throughs, and anyway, images don't make total sense in a walk-through context.  The balloon points at the GUI, and that makes the GUI visuals supreme. 

We're a small team (started out as a team of one), and so we were really lazy about specialization (as in, we don't do it).  We only use TOPIC, and we just "know" what is allowed in a given context.  We started using DITA maybe 6 or 7 years ago.  I specifically asked this group if only using topic was bad, and if one had to support all of DITA.  None other than Michael Priestly said not to worry, and that in fact he was thinking along those lines for LwDITA (if I understood him correctly).  We had to get started before LwDITA got solid, so we have what we have.  We don't support everything in DITA anyway, and indeed, for our walk-throughs we support even less.  But it works.

I'll note that we do other micro-content in popups, and that contains anything that we support overall...  Including conrefs, xrefs, and so forth.