Where Source Development Meets Documentation (for managers)


Published on

Presented at: Content Management Strategies Conference 2005

This presentation is for Managers rather than Developers.

Technical Publications organizations have been pursuing single-source solutions primarily to solve issues of quality and simultaneous production of multiple-output formats.

As organizations using single-sourcing solutions mature, content creators look for ways to:
- Streamline information gathering
- Simplify initial content development
- Automate content changes directly from product changes

Application-specific XML tools can unlock the previously isolated business systems and engineering source code. Mechanically-produced schema languages can be converted automatically into documentation and documentation templates. Content can be auto-generated simultaneously for:
- Technical Reference Manuals
- Time-Sensitive Release Notes
- API-Specific Implementation Information

Mission-critical, custom XML applications can enhance traditional single-sourcing environments by expanding the information model to include external organizations--engineering, marketing, technical support.

Practical XML development and deployment of cross-organization tools can promote efficiency and productivity by reducing maintenance and overhead.

Companies realize tangible success and immediate value-add with each application. And customers get better, more accurate, and more consistent information because information creation and publication is even more tightly woven together in an expanded single-sourcing system.

Published in: Technology
  • This presentation is for managers, see the other one with a similar name if you're a developer
    Are you sure you want to  Yes  No
    Your message goes here
  • See the original presentation description or read the full paper: http://single-sourcing.com/events/2005/04/where-source-development-meets-documentation/
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

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

No notes for slide

Where Source Development Meets Documentation (for managers)

  1. 1. Where Source Development Meets Documentation Liz Fraley Single-Sourcing Solutions, Inc.
  2. 2. A brief interlude to the real world
  3. 3. Efficiency is in the tools Many small efficiencies add up to greater gains.
  4. 4. What is source development? n Source is any programs that the company develops in house n … or integrates with!
  5. 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. 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. 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. 8. …towards 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. 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 might itself have provided metadata that was the basis for the newly- created content, in either structural or template form.
  10. 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. 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. 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. 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. 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. 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. 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 can contribute in this model
  17. 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. 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 and KB articles, and field alerts
  19. 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. 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. 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. 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. 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. 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. 25. 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
  26. 26. Thank you
  27. 27. Questions? Liz Fraley Single-Sourcing Solutions, Inc. elizabeth@single-sourcing.com