• Save
Where Source Development Meets Documentation  (or, Efficiency is in the Tools)
Upcoming SlideShare
Loading in...5
×

Like this? Share it with your network

Share

Where Source Development Meets Documentation (or, Efficiency is in the Tools)

  • 1,803 views
Uploaded on

Where Source Development Meets Documentation (or, Efficiency is in the Tools) ...

Where Source Development Meets Documentation (or, Efficiency is in the Tools)

Presented at: Arbortext User World Conference 2005

This presentation has details for Arbortext developers

The Desktop Publishing boom of the mid-80s changed the face of industry by removing the split between content and layout. On the small scale, the desktop publishing revolution was a positive change. This change was not free: The long term cost of 80s-style desktop publishing approach to document creation is that the resulting documents are by and large isolated from the larger pool of documents and the information used to create them.

Recycling content is not a new concept. What is new here is the common back-end structure in XML form and the fact that more than one set of tools, including small, mission-critical custom tools that are explicitly focused on the specific needs of a given project. There is no longer any need for one tool to address all of the needs of every company that purchases a license. Instead we have a community of tools that is easy to expand or customize without long term lock in or breaking of the model.

With only a small amount of custom tools, Juniper Networks has managed to do convert documents to multiple formats from one initial set of XML source documents and a single publishing workflow using Arbortext's Epic Editor and E3 Publishing Server. These tools have included post-processing add-ons to create .PDB and .LIT binary files and source files that are aggregated directly into the software source code for their proprietary routing platforms.

Special attention is be given to specifics of the Juniper implementation.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
No Downloads

Views

Total Views
1,803
On Slideshare
1,780
From Embeds
23
Number of Embeds
3

Actions

Shares
Downloads
0
Comments
1
Likes
1

Embeds 23

http://single-sourcing.com 15
http://www.linkedin.com 5
http://www.slideshare.net 3

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Where Source Development Meets Documentation Liz Fraley, Single-Sourcing Solutions, Inc. William Croisettier, Juniper Networks
  • 2. A brief interlude to the real world
  • 3. Efficiency is in the tools Many small efficiencies add up to greater gains.
  • 4. What is source development? n Source is any program that the company develops in house n … or integrates with!
  • 5. Sometimes source isn’t obvious n Simple tools that are being used that you don’t even know about n Things that people do to import information that no one even thinks of as “source” n but which inspect data and are dependent on its structure n You want to encourage employees to automate for efficiency n Dependencies – time lost to invisible causes when something changes … anywhere
  • 6. Source code is just a kind of information n Very specialized kind, specialized users n In most environments: n filters and transforms information (database, statistical tools) n collects information (web apps, assay machines) n produces information (simulators, …)
  • 7. Source code may be a driver in some cases… n Source is itself a product n internal or external n Source may be aimed at end-users or other source developers
  • 8. …toward information exchange n For all environments n Businesses are driven by process n The process can change! n The process is specified (ideal) n The process is ad hoc with guidelines (reality)
  • 9. Source is created by… n Source makers n New content that stands alone n Content that gets pushed back into a product n Source annotators n The product itself might have provided metadata that was the basis for the newly- created content, in either structural or template form.
  • 10. So, let’s start with pubs The goal of single-sourcing is always to n Increase the efficiency of the entire staff as the demand for documentation increases while staffing and resources do not.
  • 11. Benefits for publications n Single-sourcing: n Makes reuse possible n Improves accuracy (fix once, fixed everywhere) n Improves quality (more time per writing unit = greater quality) n Increases author collaboration n Automates simultaneous delivery of source material to multiple media n Reduces translation efforts and costs
  • 12. Benefits for publications n Separation of form from content n The desktop publishing revolution (detour) of the 80s n Return content generation expertise to authors, return formatting expertise to format experts n Correct development n Something is added, someone knows; something is deleted, someone knows; automatic red-flags in the process n Faster development n Automatically generate content or content templates
  • 13. Now, let’s add engineering… n Auto-generate content from engineering systems n Bug-tracking integration tools n Request and feature tracking tools n Produce documents with varying levels of detail n From one source, create one document appropriate for external customers, one for internal developers, and one for field engineers
  • 14. Interlude: Workflow and You n It’s easy to get developers to add something if there is no serious burden (“note to support”) and the task is “in line” with work they’re already doing. n It’s hard to get developers to add something if the work is obviously additional: n “after adding a syslog message, fill out a document explaining it”
  • 15. Interlude… n No amount of process can solve this in the real world n Water flows downhill n People do valuable “optional” work all the time (“do it right”) n People will not work extra hard to “do it right” n “Make it hard, get less” n Keep data local!
  • 16. More benefits of adding engineering to the equation… n Better diff tools n Improve review responses, quality, and general feedback (no longer limited to change bars on a PDF) n Potential to patch changes n Automated realization of code differences (API changes) n Diff of schema languages easily n Open up another avenue for original content gathering: n Domain experts contribute in this model
  • 17. Benefits aren’t limited to software engineering organizations Software/Tech Build/tools integration Biotech Database/assay machine integration Pharmaceuticals Product labeling requirements Manufacturing Integration with external systems Self-service troubleshooting Integrating diagnostic information with procedural documentation Medicine OWL initiative
  • 18. Now add customer support… n Content generated for knowledge base (KB) by an external KB vendor n Coordinate content to guarantee consistency between KB articles and documentation written from in-house publications group n Create trouble-shooting guides based on KB content and frequency of article access n Link between (inside) documents, KB articles, and field alerts
  • 19. Now add training… n Aggregate schedules of training opportunities n Use profiling to generate schedules on-the-fly for different audiences simultaneously: n This week, this month n Internal, external, management classes n All business units can participate with minimal effort
  • 20. Special benefits for training… n Reuse content from documentation and customer support to ensure information consistency n From one source, create scalable version of training materials: n Student materials n Instructor’s materials n Presentation slides n And be able to go up and down this scale to increase/decrease level of detail
  • 21. Now add marketing... n Automate creation and publication of customer price list and parts list n Profile to show price-levels n Separation of form from content makes changing look-and-feel very easy n Single-source information repository + profiling delivers consistency in white papers and data sheets
  • 22. … and sales n Reduced translation costs and efforts n Integration with customer database = easy customer portal personalization n Profile connects docs, field alerts, and KB articles relevant to the products a customer has ordered.
  • 23. Finally, a few ways to include internal business processes… n Services to support Sarbanes Oxley activities n Audit trails n Branding turnover n Acquisitions n Connecting to operations, manufacturing, and document control systems n HAZMAT database integration n W3C initiative: Universal Business Language (UBL)
  • 24. We're all sold on structure – that's why we're here n Remember: n Structure is added work n If you make structure onerous or make adding it hard/expensive time-wise, people will not do it n You need to be careful about what you choose to do or you will end up with structure that may not really be useful: <temperature>47C/104F</temperature>
  • 25. Leveraging Investment n How Juniper Networks leveraged their investment by using the Arbortext E3 Server for technical publications production n William Croisettier, tools developer at Juniper Networks n David Ngo, Consultant, Arbortext Professional Services
  • 26. Juniper’s Publishing Environment n Epic Editor n E3 n Interwoven TeamSite as the document management system for Technical Publications n Interwoven TeamSite as the content management system for Web Publishing
  • 27. How Publishing Works n Document request sent to E3 using specific parameters: n username, file name, debug state, output format request (Palm .pdb, Microsoft .lit, html, cd, etc.) n Request is sent to E3 using a CGI call sent from Interwoven TeamSite n E3 uses a request-response model to process this url and start the correct java processes
  • 28. E3 Integration n E3’s custom directory structure contains the java library code that produces html, palm, ebook, web, etc. formats from xml content n E3 returns a text message through a response object n Successful completion n Any error messages n Response object information is displayed in a popup window in TeamSite browser window
  • 29. Initial Request
  • 30. Request Processing
  • 31. Processing Results
  • 32. Multiple Uses of E3 n TeamSite has two TechPubs workflows: n TechPubs Preview for PDF output n TechPubs Production for final multi-channel publishing requests n Each workflow initiates a different publishing action from E3
  • 33. TechPubs Preview n Allows writers to preview their work in a pdf format n XML content may or may not be ready for production n Uses a FOSI to generate print output n Provides a preview functionality at any point in the writing process n Allows writers to become more efficient with more control over the final content
  • 34. TechPubs Production n Generates all multi-channel output formats from XML content n Uses the E3 request-response model with the TeamSite workflow n Generates content, but also deploys content to the correct place n a server somewhere on the intranet for the writers to approve files for posting to the Juniper extranet
  • 35. Ebook Post Processing n Intermediary final XML content file generated with E3 n E3 initiates post processing into Microsoft eBook (.lit) format by calling Readerworks API libray code n ReaderWorks API COM object called through open-source java-COM project njawin n java.library.path must be adjusted to point to dll directory
  • 36. Palm n Intermediary final XML content file generated with E3 n E3 initiates post processing into Palm iSilo (.pdb) format by using calling custom JNI code to call iSilo compiler code n JNI code uses java to call custom C code that executes iSiloXC command line compiler
  • 37. Before and After E3… n Originally used java parser to do all production work n Parser differences would interrupt production, preventing efficient automation n E3 pipeline feature helped us to chagne all parsing to E3 parser n Migrated from java DOM parser to Arbortext com.arbortext.epic.Application parser for uniformity of parser functionality and automation
  • 38. Issues n A few permissions issues: n E3 runs under a specific user n This user must also have permissions to network resources, because we copy generated content to remote servers n The Tomcat server also runs under a specific user n This user also must have permissions for network access as well…
  • 39. Results? n Juniper authors using E3 to do preview and production n True multi-channel publishing and delivery to publishing server n Automation becoming more and more important as more books roll into the system n Automation and publishing requirements met as a result of E3 integration with custom post-production code
  • 40. About Single-Sourcing Solutions, Inc. n We do XML implementation n We do XML evangelization! n We help companies develop an overall XML strategy, across all kinds of business units and business functions
  • 41. Thank you
  • 42. Questions? Liz Fraley, Single-Sourcing Solutions, Inc. Liz.Fraley@single-sourcing.com William Croisettier, Juniper Networks croisettier@juniper.net