developing xml-based user assistance at ibm and lotusxml.coverpages.org/dita-winwriters2001.pdf ·...
TRANSCRIPT
![Page 1: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/1.jpg)
Developing XML-based Developing XML-based User Assistance at IBM User Assistance at IBM and Lotusand Lotus
John HuntJohn HuntLotus Development CorporationLotus Development Corporation
Don DayDon DayIBM CorporationIBM Corporation
![Page 2: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/2.jpg)
Developing XML-based User Developing XML-based User Assistance at IBM and LotusAssistance at IBM and Lotus
Why an XML Markup Language for User Assistance?Topics, content, and structureLinking and navigationMultiple uses and presentationsSpecial Bonus:XML-based UA at Tivoli Systems
Linda Meyer and Chris Rothemich
![Page 3: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/3.jpg)
Why an XML Markup Language Why an XML Markup Language for User Assistancefor User Assistance
It is the emerging standard for deploying content, both across the internet and within software applicationsIt is part of the W3C family of Web-oriented technologies/standardsIt provides ways to address cross-browser/cross-platform issuesIt lets us easily exchange content with third-party developers
![Page 4: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/4.jpg)
Useful traits of XML for User Useful traits of XML for User AssistanceAssistance
Intent-based markup (element names can describe content meaningfully)Broad tools supportOpen resource management based on URIs (principle of XLink)Alternative to compound documents for access and reuse of partsStyle sheet driven transforms and formatting
![Page 5: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/5.jpg)
Using XML: Functional idealsUsing XML: Functional ideals
Rich in intent (semantically significant element names)Rich in typography (with style sheets)Able to be used either compiled or notAble to be reused in multiple delivery methodsLots of options for things like ToC, Index, Search
![Page 6: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/6.jpg)
Using XML: Practical idealsUsing XML: Practical ideals
Topic orientedWeb orientedFew vendor dependenciesSemantically richCan grow to meet new needs
We took these as requirements for anext-generation UA architecture... in XML!
![Page 7: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/7.jpg)
Our design approachOur design approach
Identify topics by information type, using a 'top-down' analysisIdentify ways in which topics may be "repurposed" (chapters for books, etc.)Follow W3C standards for processingExtension mechanisms should be tools-friendlyDo not rule out cutting edge ideas
![Page 8: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/8.jpg)
Result: the Darwin Information Result: the Darwin Information Typing ArchitectureTyping Architecture
Darwin - it uses principles of differentiation and inheritanceInformation Typing - it capitalizes on semantics of topics (concept, task, reference) and of content (messages, typed phrases, semantic tables)Architecture - it provides vertical headroom (new applications) and edgewise extension (derivation to new types) for information
![Page 9: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/9.jpg)
New terminologyNew terminology
DITAbase - the base DTD that contains the main topic definitions:
topic (generic, broadest)conceptreferencetask
Specialization - defining a new authoring DTD using specific naming and constraints on prior content models
![Page 10: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/10.jpg)
Topics and Information TypesTopics and Information Types
A topic is the core information unit in the Darwin Information Typing Architecture (DITA)
"A unit of information that is complete enough to describe a single task, concept, or reference item."
An information type defines the role of a topic
![Page 11: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/11.jpg)
Four Basic Information TypesFour Basic Information Types
Topic, Concept, Task, Reference
topic
task concept reference
![Page 12: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/12.jpg)
Extending the basic typesExtending the basic types
Add new information types as specializations of one of the basic types
topic
concept task reference FAQ
subtask F1 help API messages
LotusScript C++ Java
![Page 13: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/13.jpg)
Topic types in Lotus Notes and Topic types in Lotus Notes and Domino "End-user" HelpDomino "End-user" Help
Assumption: All topics are either tasks or conceptsTask topics
Any topic with a Numbered list that's not in a table
Concept topicsAll other topics
Loose endsTroubleshooting, FAQs, Glossary
![Page 14: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/14.jpg)
Process: First derive "generic" Process: First derive "generic" topicstopics
topic
title
prolog
metadata
relgroup
body
p, note, ol, ul, table, etc.
topic | concept | reftopic | task
![Page 15: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/15.jpg)
Then morph "topic" to "task"Then morph "topic" to "task"topic
title
prolog
metadata
relgroup
body
task
title
prolog
metadata
relgroup
taskbody
prereq
context
steps
taskxmp
result
postreq
step
cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?
![Page 16: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/16.jpg)
This "Generic" topic...This "Generic" topic...<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE topic SYSTEM "ditabase.dtd"><topic>
<title>To choose a location</title><prolog>
<relgroup role="friend" dupes="nodupes"><link url="H_CREATE.xml">Creating locations </link><link url="H_SPECIFY.xml">To switch a User ID</link>
</relgroup></prolog>
<body><ol>
<li>Choose File - Mobile - Choose Current Location.</li><li>Select a location.</li><li>If necessary, click OK.</li>
</ol></body></topic>
topic
titleprologrelgroup
body
![Page 17: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/17.jpg)
becomes this "task" topicbecomes this "task" topic<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE task SYSTEM "ditabase.dtd"><task>
<title>To choose a location</title><prolog>
<relgroup role="friend" dupes="nodupes"><link url="H_CREATE.xml">Creating locations </link><link url="H_SPECIFY.xml">To switch to a User ID</link>
</relgroup></prolog>
<taskbody><steps>
<step><cmd>Choose File - Mobile....</cmd></step><step><cmd>Select a location.</cmd></step><step><cmd>If necessary, click OK.</cmd></step>
</steps></taskbody></task>
task
title
prolog
relgroup
taskbody
steps
step/cmd's
![Page 18: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/18.jpg)
General patterns for more General patterns for more complex task topicscomplex task topics
Cast "indented" content as infoAll subheadings start a new sub-topic
Content preceding the task becomes a sub-task section of taskbody/context Content following the task becomes a sub-task section of taskbody/result
![Page 19: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/19.jpg)
What about tables?What about tables?
Content in a table is very interesting, XML-wise!Notes task topics contain lots of two-column tables
Option - DescriptionClick... - To...Name - Mood Stamp
Can represent most two-column tables in DITAbase as a dl "definition list"
![Page 20: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/20.jpg)
Examples from Notes End-user Examples from Notes End-user HelpHelp
"Basic" tasks with context, steps, resultTo change the size of SmartIcons
Tasks with sub-tasksUsing database libraries to group databases
![Page 21: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/21.jpg)
Examples from Notes End-user Examples from Notes End-user Help Help (continued)(continued)
"Big" task with sub-tasksEmbedding data in a Notes document
Option - Description table in a taskCreating appointments, anniversaries, reminders, and all-day events
A "concept" topicNavigation buttons: moving around
![Page 22: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/22.jpg)
Linking and navigationLinking and navigation
Ditabase provides several ways to specify a link
xreflinkrefldesc
A relgroup in the topic prolog lists "see also's" or "related topics"
Link attributes provide additional detailurlrole (parent, child, friend, sibling)type (topic-type; fig, table, list, heading)
![Page 23: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/23.jpg)
TOC, Index, and SearchTOC, Index, and Search
Have experimented with:Using JavaHelp XML ToC & Index files plus DHTML to produce ToC and Index navigators
No widespread solution yet for XML search
![Page 24: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/24.jpg)
Multiple uses and presentation Multiple uses and presentation using XMLusing XML
XML-based topics are well-suited for use as:
content for UA helpsetscontent for Web-based info centerssection or chapter content for bookssections for POD bookletsarticles for journals or technical newslettersmany others!
![Page 25: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/25.jpg)
How to reuse a topicHow to reuse a topic
What use do you want to make of this topic? This is an "application context."Devise a DTD to represent how the new application uses the topics:
provides link access between topicsenables making indexes and ToCsprovides ways to attach new overviews or styling concerns
![Page 26: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/26.jpg)
How to reuse a topicHow to reuse a topic (continued) (continued)
Write additional XSLT template rules augment the basic set (HTML output) with rules for the new, superset elementsoverride existing template rules that need to be treated differently in the new context
If the new application is greatly different, rewrite the processors accordingly (XSL Formatting Objects, other XML)
![Page 27: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/27.jpg)
Mechanisms for reuseMechanisms for reuse
Definitional components that can be moved to a high-level location:
link descriptions (rels, links)bibliographic descriptionsclass definitions ("casts" for elements)document metadata
Referencing components:local implementation of XIncludecitations, cross-referenced labels
![Page 28: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/28.jpg)
How to extend a topicHow to extend a topic
Relate the new "info type" to an existing type (concept, reftopic, task, or something new classed directly from a generic topic) Define new specialized element namesWithin content models of the same kind, you can further constrain allowed content, or redefine things of a kind (upwardly transformable)
![Page 29: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/29.jpg)
How to extend a topicHow to extend a topic (continued) (continued)
Create an authoring DTDCreate a supporting XSL style sheet:
map new elements/attributes to existing "base" template rulesaugment with new template rules where a processing rule does not exist
Document the new specialization
![Page 30: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/30.jpg)
ConclusionsConclusions
Is an XML for user assistance possible?Yes.
Has it worked?Yes. We already moved over 7,000 topics and 5,000 pages of Notes/Domino content into DITAbase XML.
Stay tuned.The story goes on...
![Page 31: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/31.jpg)
Demo of XML-based user Demo of XML-based user assistance at Tivoli Systemsassistance at Tivoli Systems
Chris RothemichLinda Meyer
![Page 32: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/32.jpg)
LinksLinks
Notes.netDomino & Notes Doc Library
www.alphaworks.ibm.comwww.lotus.com/xmlwww.ibm.com/developer/xml
![Page 33: Developing XML-based User Assistance at IBM and Lotusxml.coverpages.org/DITA-winwriters2001.pdf · Developing XML-based User Assistance at IBM and Lotus Why an XML Markup Language](https://reader030.vdocuments.site/reader030/viewer/2022041109/5f0d07557e708231d43852ab/html5/thumbnails/33.jpg)
Contact InformationContact Information
John HuntUser Assistance ArchitectLotus Development [email protected]
Don DayAdvisory Software EngineerIBM [email protected]