Dynamic DITA Delivery for Help

Distributed Dynamic Documentation Displayfor Distributed, Dynamic Applications

Chris Despopoulos

1

Chris Despopoulosdespopoulos_chriss@yahoo.comhttp://www.cudspan.net

• Technical writer for decades (since 1988)• FDK developer

CudSpan tools for FrameMaker• Currently working full time for VMTurbo

http://www.vmturbo.com/

Note: Please excuse the cheesy clip-art

Introductions

• Problem Statement• Strategy• Road Map – Where we are today• Demo – Dynamic DITA Display• Conclusion• Q & A

Agenda

But First…

Background – Comfort Level With:

• DITA• Web Document Servers• Web Apps• Mashups• Client/Server Applications• Distributed Applications• VMs – Virtual Machines

Intelligent Workload Management for Virtual and Cloud Infrastructures (Software Defined Control)• VMTurbo solution

• Economic principles – Supply and demand to manage environment • End-to-End Automation

• Planning for success• We want millions of our products out there• Hundreds of millions of VMs – Many serving distributed applications

• IMPORTANT: Our product is a VM appliance that serves a Web AppWeb App = Web Server – Each product installation serves its own docs

This is interesting because it inspired this very presentation

Background – VMTurbo Business

Problem Statement

Distributed Application – A Services Mashup

• From VM Network to Operations Manager

Virtual Network

• From Operations Manager to Operations Manager – Master/Slave

Distributed Application – A Services Mashup

Virtual Network

• What happens when we add another product to the offering? For example, User Manager to track user statistics… Master integrates two different types of work.

• How complex can this architecture become?

• From VM Network to Operations Manager• From Operations Manager to Operations

Manager – Master/Slave

To arrive at a strategy, one should state the problem in the abstract – Please bear with me…

Strategy Needed

Problem:For an arbitrary distribution of application services, how do we document applications that mash up those services?

Strategy

Documentation Strategy?

Static HTML

• Most common delivery today (my opinion)• Generated by HAT, DITA OT, or other means• Separate set of files for each “product”• Becomes a nightmare

Documentation Strategy?

Central Doc Server:• Currently on the market – RoboHelp Server, MadCap

Pulse, etc.• Content can be dynamic – DITAweb from Mekon, for

example• Great features – User-authored content, reporting, etc.

BUT…• Licensed per domain – To be cost effective, relies on external

network connection (not all customers allow that)• More importantly, must mirror distributed app complexity – Will

it scale?• Tactically it works, but in the abstract it isn’t a valid strategy

(for me, anyway)

Dynamic• Each node manages its own user profiles (conditional text)• Each node manages its own “extra” data (user-authored

content, product API, 3rd party, etc.)• Aggregating node:

• Merges docs from target nodes to “maintain its own doc set”• Merges “extra” data • Can push “extra” data down to target

Distributed • Each node maintains its own doc set• Similar to topic-based writing, each doc set is self-sufficient• Service node update = doc update – By Definition

Strategy: 4D – Distributed Dynamic Doc Display

Road MapWhere we are today

Tactics: Road Map

Static HTMLOld Solution

Dynamic DITA DisplayReplicate Static HTML

Simple DynamicsUser Profiles, Rebranding

Advanced DynamicsUser Content, Input from API

Full 4D!Merge from different products

• Source in FrameMaker• HTML generated via proprietary tools• Static HTML files• Files manually copied into build repository• GUI in Flex – Help calls hard-coded

State of Product Help Yesterday

• Minimal HTML as a “container” for the content• Raw DITA on the application server• AJAX to retrieve content• DITA transformed to HTML on the fly

• TOC built from DITA map• HTML topics built from DITA topics

• Help calls mapped by IDs in JavaScript• Version 1 replicates traditional static HTML help

State of Product Help Today

First baby steps toward 4D pubs

OLD (Simple)• HTML is static:

• No response to product state, user account, etc.• No rebranding• Difficult to support user-generated content

• “Skin” is bound to each static file – Hard to change look

Web Server

Web ClientXSL Transform

XML

AJAX Request

HTML

HTML Content

HTML

HTML Skin/Javascript

CGI Hook

Other data sources:• API• Target Appliance• Etc.

NEW (Complex – machine does the work)• HTML files are a container to display content – Easy to skin

• AJAX calls get DITA topic or map, transform it into HTML content

• Minimal activity on the server side – confined to the doc area

• CGI currently just gets XML files – Will access other data in the future

Help Display

OLD (Complex – human does the work)• Edit content in word processor

• Binary source on local disk

• Archive past versions as zips

• Save as HTML

• Process HTML to get help format

• Manually check in files• Delete old HTML from local repository

• Copy new files in

• Synchronize/commit

• Generate PDF – 1 hour

• Takes 2 – 4 hours for each HTML delivery (many deliveries per release)

NEW – XML Source in SVN (Simple)• Edit topics – Commit changes

• Open topics in word processor and generate PDF – 1 hour

Authoring & Delivery – Immediate Win

• Agile – Changes show in the product as I make them• Review – More immediate, and in full product context• Custom Release – If we send out a special build for a special customer, the

latest docs are in place

• Branching – I have the same process for branches and patches as the developers

• Inexpensive – SVN is free, that’s all I need• Works for a small shop – Lowers the bar for DITA uptake

Authoring & Delivery – Immediate Win

Demo

In Conclusion…

Bad News• Just a prototype – Lots of wires hanging out the

back of the box• Minimal DITA support• Needs lots of refactoring

Good News/Bad NewsGood News• Permission from VMTurbo to go Open Source• Lightweight DITA proposal for DITA 1.3

• On the horizon – compatible with this project• http://dita.xml.org/blog/lightweight-dita-at-

cmsdita-north-america-2013

• Michael Kay has Saxon-CE (client edition)• JS XSLT 2.0 – You REALLY should check it out!• Might be a better road to 4D• Open Source!• http://www.saxonica.com/ce/index.xml

• Virtual infrastructure is bringing change• Expect more client/server apps• Expect more distributed apps• Expect more complexity

• 4D Pubs – One way to address this complexity• Doc mashups to match service mashups• Documentation stays with the service node – where it belongs• Documentation can have unlimited sources of input data

• First Steps!• Delivered in real product, today• Even at its most mundane, it has advantages• Advanced features in the works

• You can play with it today – Meet me later in the bar with a WAMP server on your machine and let’s see…

To Summarize…

Thank You