Embed Size (px)
Citation preview
08 Dec 2001 STC Conference, Bangalore 2
What We’ll Cover
What is single sourcing? How does single sourcing help? What is XML? Why XML? Single sourcing with XML Some examples
08 Dec 2001 STC Conference, Bangalore 3
The Problem
Company X is launching a new software product that will be deployed on UNIX and Windows.
Your job is to create a documentation suite consisting of: online help user manual readme quick start card release notes error messages FAQs
08 Dec 2001 STC Conference, Bangalore 4
Traditional Documentation Scenario
ERS
User Manual
Readme
Quick Start
Error Messages
Release Notes
Online Help
FAQs
Each doc product is an island of information, and needs to be
maintained individually.
08 Dec 2001 STC Conference, Bangalore 5
Problems in the Traditional Documentation Scenario
Redundancy and repetition of information Maintenance overheads
– rework– scope for errors– inconsistencies of style and format
No time to improve content and usability Tight integration of format and content leads
to a high dependence on tools
08 Dec 2001 STC Conference, Bangalore 6
Single Sourcing Scenario
ERS
User Manual
Readme
Quick Start
Error Messages
Release Notes
Online Help
FAQs
Single Source
08 Dec 2001 STC Conference, Bangalore 7
What Is Single Sourcing?
Single sourcing means writing content once and using it
many times separates how information “is” from how it
“looks” allows you to create and manage
information as reusable objects
08 Dec 2001 STC Conference, Bangalore 8
Information as Objects
User manual
Single source
Quick Start
08 Dec 2001 STC Conference, Bangalore 9
How Single Sourcing Helps
Eliminates repetitive and redundant information
Reduces maintenance errors Increases collaboration through object
orientation Increases cost effectiveness by reducing
effort on documentation Increases consistency across documents
08 Dec 2001 STC Conference, Bangalore 10
Where does XML fit in?
08 Dec 2001 STC Conference, Bangalore 11
What is XML?
eXtensible Markup Language or XML is a
data standard that allows you to break up a
document into elements and identify the
different elements.
08 Dec 2001 STC Conference, Bangalore 12
Why XML?
Open source technology– Non-proprietary– Cheap– Versatile
Universal data exchange format
08 Dec 2001 STC Conference, Bangalore 13
Some related terms...
Styling: a means of displaying XML documents Examples: CSS, XSL, DSSSL
Document Type Definition: a collection of elements and the rules governing their relationship(The DocBook DTD is of particular relevance to technical communicators.)
08 Dec 2001 STC Conference, Bangalore 14
Demo
Using Jade and DocBook Using XML and XSL
08 Dec 2001 STC Conference, Bangalore 15
Case 1: Using the DocBook with Jade
08 Dec 2001 STC Conference, Bangalore 16
What You Need:
Jade: a freely downloadable conversion engine
The DocBook DTD: a freely downloadable DTD for technical writing and publishing
Style sheets: freely downloadable modular style sheets that work with Jade
An editor: Preferably, an XML editor like Xemacs; otherwise, Notepad will do
08 Dec 2001 STC Conference, Bangalore 17
How to Make It Work:
Identify the logical requirements(What are my deliverables?)
Identify the physical information requirements (Which parts of the information can I reuse?)
Create DocBook-conformant XML files. Use Jade to parse your document to create HTML,
RTF or TeX output. Use Jadetex to create PS and PDF files.
08 Dec 2001 STC Conference, Bangalore 18
Case 2: Use XML with XSL
08 Dec 2001 STC Conference, Bangalore 19
What You Need:
A text editor(like Notepad)
An XML processor(like Xalan or Cocoon)
08 Dec 2001 STC Conference, Bangalore 20
How to Make It Work:
Identify the logical information requirements (What are my deliverables?)
Identify the physical information requirements (Which parts of the information can I reuse?)
Create your XML files. Create style sheets corresponding to each
deliverable type. Generate output using an XML processor.
08 Dec 2001 STC Conference, Bangalore 21
Resources
Useful Links on XML/XSL http://www.w3.org/xml/ http://www.xml.org/ http://www.w3.org/Style/XSL/
Books on XML/XSL Goldfarb, CF and Prescod P (1999): “The XML Handbook”. Prentice
Hall, NJ. Elliotte RH (1999):”XML Bible”. IDG Books. India Doug, T (2001): “XSLT”. O’Reilly & Associates.
08 Dec 2001 STC Conference, Bangalore 22
Resources
DocBook http://www.docbook.org/
Jade http://www.jclark.com/jade/
DSSSL http://www.jclark.com/dsssl/
Other XML Editors/Processors http://www.xmlspy.com/ http://xml.apache.org/xalan-c/index.html http://sourceforge.net/projects/jadetex/
08 Dec 2001 STC Conference, Bangalore 23
Thank you!
