4D Pubs - Distributed Dynamic Document Dsplay


Published on

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.

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

4D Pubs - Distributed Dynamic Document Dsplay

  1. 1. Dynamic DITA Delivery for Help Distributed Dynamic Documentation Display for Distributed, Dynamic Applications Chris Despopoulos 1
  2. 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. 3. • Problem Statement • Strategy • Road Map – Where we are today • Demo – Dynamic DITA Display • Conclusion • Q & A Agenda
  4. 4. But First…
  5. 5. Background – Comfort Level With: • DITA • Web Document Servers • Web Apps • Mashups • Client/Server Applications • Distributed Applications • VMs – Virtual Machines
  6. 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. 7. Problem Statement
  8. 8. Distributed Application – A Services Mashup • From VM Network to Operations Manager Virtual Network • From Operations Manager to Operations Manager – Master/Slave
  9. 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. 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. 11. Strategy
  12. 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. 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. 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. 15. Road Map Where we are today
  16. 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. 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. 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. 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. 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. 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. 22. Demo
  23. 23. In Conclusion…
  24. 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. 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. 26. Thank You