Upload
chris-despopoulos
View
144
Download
0
Tags:
Embed Size (px)
DESCRIPTION
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.
Citation preview
Dynamic DITA Delivery for Help
Distributed Dynamic Documentation Displayfor Distributed, Dynamic Applications
Chris Despopoulos
1
Chris [email protected]://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