In a distributed environment with many service nodes, documentation should be distributed with those service nodes. Documentation should also be dynamic. These slides were for a presentation of a working system.

1. Dynamic DITA Delivery for Help
Distributed Dynamic Documentation Display
for
Distributed, Dynamic Applications
Chris Despopoulos
1

2. Chris Despopoulos
despopoulos_chriss@yahoo.com
http://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

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

4. But First…

5. Background – Comfort Level With:
• DITA
• Web Document Servers
• Web Apps
• Mashups
• Client/Server Applications
• Distributed Applications
• VMs – Virtual Machines

6. 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 App
Web App = Web Server – Each product installation serves its own docs
This is interesting because it inspired this very presentation
Background – VMTurbo Business

7. Problem Statement

8. Distributed Application – A Services Mashup
• From VM Network to Operations Manager
Virtual Network
• From Operations Manager to Operations
Manager – Master/Slave

9. 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

10. 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?

11. Strategy

12. 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

13. 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)

14. 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

15. Road Map
Where we are today

16. Tactics: Road Map
Static HTML
Old Solution
Dynamic DITA Display
Replicate Static HTML
Simple Dynamics
User Profiles, Rebranding
Advanced Dynamics
User Content, Input from API
Full 4D!
Merge from different products

17. • 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

18. • 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

19. 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 Client
XSL
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

20. 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

21. • 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

22. Demo

23. In Conclusion…

24. 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 News
Good 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

25. • 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…

26. Thank You