Single Source Publishing with XML - Louis-Pierre GUILLAUME
Transcript of Single Source Publishing with XML - Louis-Pierre GUILLAUME
![Page 1: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/1.jpg)
On-Line Help ConferenceEurope 99
SchlumbergerOilfield Services
Single Source Publishingwith XML
Louis-Pierre Guillaume June 4, 1999
Documentation manager On-Line Help Conference
IT/BMS London, [email protected]
![Page 2: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/2.jpg)
2
Summary
1. History2. Structure of the documentation3. What is XML?4. New Authoring System (XML Workbench)5. Specification and conversion6. Publishing process7. Lesson learned
![Page 3: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/3.jpg)
3
1. History
◆ Schlumberger has implemented SAP
◆ The end-user documentation was a WinHelpon-line help (about 5000 pages)
◆ 12 man-years to author version 5
◆ Authored by former field people (trainers)
◆ CD-ROM publishing
◆ Authoring with Word, translation to RTF,conversion to WinHelp
![Page 4: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/4.jpg)
4
Objectives of the documentation
◆ To help the end-user to perform tasks, by:• giving a big picture of the business processes
• giving detailed procedures for each task
• providing FAQs, hints, and tricks
Teach the end-user how to fish
![Page 5: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/5.jpg)
5
◆ Organized around the concept of process:
◆ Navigation inside HOL:• buttons, hyperlinks, TOC, Index, full-text search,
search by natural language
2. Structure of the documentation
Process Process narrative
Flow chart of tasks
Tasks 1
Tasks n
Page 1
Page m
Steps to follow
Screen captures
Sub-tasks
......
Total: 200 Processes, 100 Reports, 500 Tasks, 2000 Screen captures
![Page 6: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/6.jpg)
6
Modularity of the documentation
◆ 800 XML documents (500 tasks, 300narratives)
◆ 2000 screen captures (GIF files)
◆ 200 flowcharts (Visio + Image map)
◆ 4000+ links
◆ Each XML document and flowchart containsmeta-data (its status)
◆ Each document follows a naming convention
![Page 7: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/7.jpg)
7
Web interface: A Process Narrative
![Page 8: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/8.jpg)
8
Web interface: Annotated screencapture of the SAP GUI
![Page 9: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/9.jpg)
9
Web interface: A Task
Pop-up
![Page 10: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/10.jpg)
10
Web interface: Indexes
Action verbs SAP transaction codes
![Page 11: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/11.jpg)
11
Single Source Publishing with XML
1. History2. Structure of the documentation
4. New Authoring System (XML Workbench)5. Specification and conversion6. Publishing process7. Lesson learned
3. What is XML?
![Page 12: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/12.jpg)
12
3. What is XML?
◆ eXtensible Markup Language
◆ W3C Recommendation, Feb 1998 (XML 1.0)
◆ XML is a subset of SGML• “The goal of XML is to enable generic SGML
(Standard Generalized Markup Language) to beserved, received, and processed on the Web in theway that is now possible with HTML.”
![Page 13: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/13.jpg)
13
XML vs. HTML
◆ HTML: language for visual presentation of adocument; it is an application of SGML (adocument type definition = DTD).
◆ XML: meta-language for designing documentcontents; it is an abbreviated version of SGML,to make it easier for you to define your owndocument types, and to make it easier forprogrammers to write programs to handle them.
![Page 14: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/14.jpg)
14
Example of XML and HTML
◆ HTML<CENTER><H3>How do I change a Master...</H3></CENTER><H4><FONT COLOR="#006600">Overview</FONT></H4><UL><LI><B>Purpose: </B>Use this process to change...</LI></UL>
◆ XML<Title ID="8837"><Title-body>How do I change a Master...</Title-body></Title><Overview>
<Purpose><Para><Text>Use this process to change...</Text></Para></Purpose><Trigger><Para><Text>You receive a notification...</Text></Para></Trigger>
</Overview>
![Page 15: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/15.jpg)
15
4. New XML authoring system
◆ Goal:• Harmonize the authoring of the documents• Facilitate the update• Manage the translations• Manage the variants (area and PL specificities)• Publish through several media (Web, print...)• Publish customized variants on demand
◆ Solution:• XML authoring system
![Page 16: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/16.jpg)
16
New XML authoring system (cont.)
◆ Tools:• XML editor (Arbortext Adept Editor)• XML Doc. Man. System
– Novasoft NovaManage (Doc. Man. System)– INSO Balise (SGML/XML middleware)
• Converter to HTML (INSO HTML-Package)• Composer to PDF (Adobe Frame Maker + SGML)
![Page 17: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/17.jpg)
17
Single Source Publishing with XML
1. History2. Structure of the documentation3. What is XML?4. New Authoring System (XML Workbench)
6. Publishing process7. Lesson learned
5. Specification and conversion
![Page 18: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/18.jpg)
18
5.Specification and conversion
1. Conception of 2 Document Type Definitions (DTDs)
2. Conversion from RTF to XML
![Page 19: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/19.jpg)
19
Conception of 2 DTDs
◆ Analysis of the document types:• 2 types identified (task, narrative)
• Structure of each type very homogenous
◆ Creation of the DTDs:• Reuse the Schlumberger corporate DTD
• Creation of elements specific to the SAP GUI
◆ Importance of the role of the contractor (AIS)
![Page 20: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/20.jpg)
20
Example: DTD for "Narratives"
1 or more0 or moreOr
![Page 21: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/21.jpg)
21
Conversion from RTF to XML
◆ Source RTF is tagged with "WinHelp" codes
◆ Converter:• Built on Balise
• Uses heuristics to extract the semantic
◆ Cleaning-up of the data:• Iterative work (conversion, "log" analysis, cleaning-
up of the RTF or modification of the XML)
• Takes time, requires a lot of care
![Page 22: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/22.jpg)
22
Example: RTF => XML$ # > { b m c E : \ m m - \ G R A P H I C S \ S L - S M A L L . B M P } H o w d o I c r e a t e aC o n t r a c t R e l e a s e O r d e r ?
O v e r v i e w
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P }P u r p o s e : U s e t h i s p r o c e s s t o c r e a t e ( r e l e a s e )
p u r c h a s e o r d e r s b a s e d o n t h e p r i c e s a n d c o n d i t i o n sd e f i n e d i n a c o n t r a c t w i t h a v e n d o r .
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P } T r i g g e r :A r e q u i r e m e n t e x i s t s f o r a m a t e r i a l , e x t e r n a l s e r v i c e o r a na s s e t t h a t i s c o v e r e d u n d e r a c o n t r a c t .
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P } R e s u l t :A p u r c h a s e o r d e r i s c r e a t e d ( r e l e a s e d ) t o a v e n d o r t h a tu s e s t h e c o n t r a c t a s a r e f e r e n c e . E a c h p u r c h a s e o r d e rr e l e a s e u p d a t e s t h e a c c u m u l a t e d s t a t i s t i c s o f t h e c o n t r a c t .
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P }P e r f o r m e d b y :
W a r e h o u s e / S t o r e / M a t e r i a l / A d m i n i s t r a t i v e S t a f f
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P } U s e d b yw h i c h P r o d u c t L i n e s : A l l
W h a t d o I n e e d t o k n o w ?
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L B L U E . B M P }P r e r e q u i s i t e s / d a t a :
{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L G R E E N . B M P }C o n t r a c t n u m b e r{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L G R E E N . B M P }Q u a n t i t y t o r e l e a s e{ b m c w d E : \ m m - \ G R A P H I C S \ S M A L L G R E E N . B M P }D e l i v e r y r e q u i r e m e n t s
$ C r e a t e a C o n t r a c t R e l e a s e O r d e r
# M M _ C C R O _ P H _ C O M
> m a i n u
<title><title-body>How do I create a Contract ReleaseOrder?</title-body></title>
<overview><purpose><para><text>Use this process to create (release) purchase ordersbased on the prices and conditions defined in a contract with a
vendor.</text></para></purpose><trigger><para><text>A requirement exists for a material, external serviceor an asset that is covered under a contract.</text></para></trigger><results><para><text>A purchase order is created (released) to a vendor
that uses the contract as a reference. Each purchase order releaseupdates the
accumulated statistics of the contract.</text></para></results><performed-by><para><text>Warehouse/Store/Material/Administrative
Staff</text></para></performed-by><used-by><para><text>All</text></para></used-by></overview><need-to-know-first><prerequisites><para><unord-list><list-item><para><text>Contract number</text></para></list-
item><list-item><para><text>Quantity to release</text></para></list-item><list-item><para><text>Delivery requirements</text></para></list-item></unord-list></para></prerequisites>
Naming Convention
![Page 23: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/23.jpg)
23
Single Source Publishing with XML
1. History2. Structure of the documentation3. What is XML?4. New Authoring System (XML Workbench)5. Specification and conversion
7. Lesson learned6. Publishing process
![Page 24: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/24.jpg)
24
6. Publishing process
1. Update of the documents by the writers (trainers)
2. Multi-formats publishing (HTML, PDF…)
![Page 25: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/25.jpg)
25
Update of the documents
◆ Authoring process:• 12 writers on the same floor• Editing of the documents in Adept:
– Controlled environment– Macros to speed up the authoring
• Visualization in HTML for control• Check into the document management system• Quality control (structure, content, and links)• Inclusion of annotated screen captures• Creation of flowcharts with hyperlinks
![Page 26: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/26.jpg)
26
Authoring process with XML
◆ Ease of use of the XML editor:• The writers did not know XML
• The DTDs allow them to concentrate on the content,not on the formatting
• The DTDs ensure consistent documentation
• HTML viewer is mandatory
• Very positive learning curve
◆ Strong support needed in the beginning• Assistance from local "help desk" necessary
![Page 27: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/27.jpg)
27
Management of the documents
◆ The EDMS is easy to use
◆ The authoring system is a success
◆ Some inconvenient:• Glossary on database not easy to update
• Flowcharts are on 2 formats
• Update of buttons somewhat cumbersome
• The 2 DTDs have some limitations
![Page 28: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/28.jpg)
28
Publishing
◆ Construction of the help-on-line:• Export of the last updated documents (XML, GIF,
"images map")
• Construction of the navigation tools (links, indexes,tables of content)
• Creation of more than 3000 HTML files
• Compilation with HTML-Help to check links
• Integration to SAP for context sensitivity
![Page 29: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/29.jpg)
29
Publishing of the HOL
Conversiontool forexport
Definitio
ns
XML files
Pre-conversion
Doc. Man.System
Revision dataLin
ks
Glossary
Term-Def.
Term-Def.
Term-Def.
Pre-processing
Screen captures (GIF)
Flowcharts (GIF + HTML)
Images of buttons (GIF)Flowcharts (Visio)
XML file
Page1
Page2
Page3
Sub-task3-1
HTML files
Published HOL
SAP
Pre-processing
Links to SAP HOL
Code-URL
Code-URL
Code-URL
HTML files
Page1
Page2
Page3
Sub-task3-1
TOC1
TOC2
Index1 Index
2
![Page 30: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/30.jpg)
30
Publishing (cont.)
◆ Production of print:• Extraction from the database for a specific population
• Creation of manuals through a composition tool(Frame Maker + SGML)
◆ Multilingual translation (future plan):• From English to French and Spanish
• Semi-automatic translation (memory translation)
• Database management of the translated modules
![Page 31: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/31.jpg)
31
Single Source Publishing with XML
1. History2. Structure of the documentation3. What is XML?4. New Authoring System (XML Workbench)5. Specification and conversion6. Publishing process7. Lesson learned
![Page 32: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/32.jpg)
32
7. Lesson learned
◆ Preparing your project
◆ Writing the specifications
◆ Working with an external consultancy
◆ Before go live
◆ After go live
![Page 33: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/33.jpg)
33
Preparing your project
◆ Get the right documentation
◆ Learn XML
◆ Go to experts (company or outside)
◆ Learn what EDMS can do
◆ Get the right tools
◆ Plan your project
![Page 34: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/34.jpg)
34
Writing the specifications
◆ DTDs, conversion to XML, export to HTML• Analyze your documents
• Identify their complexity
• Specify as much as you can
◆ Document management system• Have a look on existing specifications
• Identify the documentation processes and the actors
• Identify the system requirements
• Write the request for bids
![Page 35: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/35.jpg)
35
Working with an external consultancy
◆ Be ready to discuss technical issues with it, orget somebody to do it for you
◆ Test, test, and test again
◆ Listen to your contractor
◆ Get the proper documentation from it
![Page 36: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/36.jpg)
36
Before go live
◆ Test, test, and test
◆ Install the software on the users’ computers
◆ Train the users
◆ User documentation
![Page 37: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/37.jpg)
37
After go live
◆ Help desk
◆ Be ready to fine tune
◆ Quality control
◆ Prepare future updates
![Page 38: Single Source Publishing with XML - Louis-Pierre GUILLAUME](https://reader036.fdocuments.us/reader036/viewer/2022071600/613d2f4f736caf36b75a526f/html5/thumbnails/38.jpg)
38
Questions?