4D Pubs - Distributed Dynamic Document Dsplay
Upcoming SlideShare
Loading in...5

Like this? Share it with your network


4D Pubs - Distributed Dynamic Document Dsplay



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

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.



Total Views
Views on SlideShare
Embed Views



0 Embeds 0

No embeds



Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

4D Pubs - Distributed Dynamic Document Dsplay Presentation Transcript

  • 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