Date post: | 28-Dec-2015 |
Category: |
Documents |
Upload: | joella-riley |
View: | 216 times |
Download: | 0 times |
IBM Corporate User Technologies
January 10, 2005 © 2004 IBM Corporation
An Introduction to Darwin Information Typing Architecture: DITA
Don Day, Chair, OASIS DITA Technical CommitteeIBM Lead DITA ArchitectPresented to OASIS Business Centric Methodology Technical Committee
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation2
AgendaAgenda
History of DITA – Why was DITA developed?
Introduction to DITA – What is DITA?
Benefits of DITA – Why should you care?
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation3
What you will hear
DITA is about making life easier in the realm of technical writing
• For authors, for editors, for managers, for collaborators, for information architects, for developers supporting the teams, for customers
DITA is about reuse• Focus on topic authoring based on an information
architecture which supports recombination and specialization
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation4
Background: Why DITA?Background: Why DITA?
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation5
History of markup in IBM
Limited reuseSingle purpose
1970s:ISIL
Printed books
1980s:BookMaster,
IPF
Printed and online books, online help
One book-centered DTDInformation architecture
1990s:SGML, HTML
Online information, webs, printable &
printed books
Need for change in 1990s
Components, multiplatform, open
systems
Web-deployed products and informationPartner and OEM use of information
2000+XML-based semantics
Alternatives to books
Shorter cycles, fewer people versus monolithic DTDs, long learning curves. Need for faster, cheaper. Reuse.
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation6
Identify the need – Historic convergences within IBM
Initiation of an IBM task force on information architecture
Focus by technical writing community on Minimalism
Development of XML by World Wide Web Consortium (W3C)
Trend away from SGML-era design thoughts (IBMIDDoc DTD)
Recognized need for alternative that would provide:• Shorter development cycles
• Variability in HTML outputs
• Componentization of products
• Reuse of common information components
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation7
Identify the need – Customer issues
Solutions, not products• Integration of information
Information glut• More meaningful information (role & task based)
Out-of-date information in books• Updating and maintaining information
Reduce cost of deployment of information• Provide information integrated or on-line
Reduce support costs• Customize and update information
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation8
Identify the need – The Vision (1998/1999)
Single source
XML topic
1
XML topic
2
XML topic
3
XML topic
4
1
2
3
2
3
4
Multiple contexts
Information web A:
1, 2, 3
Print A:1, 2
Information web B:
2, 3, 4
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation9
Address the problem – Charter XML Work Group
Appointed a technical / thought lead Recruited a community of technical leads
• Top of line knowledge
• Top of line passion
Defined charter and scope of the WG• Consider trends, research in information architectures
• Exploit XML and related technology standards
• Extend into areas outside ownership to define boundaries
• Mentor/Offer competence to others• Establish thought leadership• Develop and enhance analytic skills
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation10
Promise and Reality of XML
Promise• Separation of content from form: reuse content in different
presentation media
• Use specific markup to describe your content
• Use standard solution to enable easy exchange of information Reality – Generic XML
• Generic XML provides an SGML with simpler syntax but similar problems
• Generic solutions may not be specific to your needs
• Knowledge representation is strongly related to current corporate culture; fixed schemas carry past issues throughout the lifecycle.
Tradeoff• The more useful your markup is to you, the more it will cost you and
the fewer people will share the costs
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation11
The result: DITA
First published on developerWorks March 2001
Prototyped internally for a year
Development of internal, external communities for tools, users
Movement toward open standards and open source
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation12
What is DITA?What is DITA?
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation13
DITA defined
Darwin: DITA utilizes principles of inheritance for specialization
Information Typing: DITA was originally designed for technical information based on an information architecture of Concept, Task and Reference
Architecture: DITA is a model for extension both of design and of processes
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation14
Core design principles of DITA Topic orientation
• Discrete units of information covering a specific subject with a specific intent
Topic granularity• Self-contained topics combine with other topics into
information sets Strong typing
• DTDs and schemas guarantee that DITA types follow identical information structures
Specialization• Architecture for extending basic types to new types adapted
for a particular use within an information set Common base class
• Top-level "generic" base type provides “fallback” for all types
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation15
The core DITA information types – The “IT” in DITA
topic
concept task reference
Provides background information that users need to know.
Provides quick access to facts.Provides procedural details such as step-by-step instructions.
A unit of information which is meaningful when it stands alone.
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation16
Types of reuse with DITA
Reuse of Content
Reuse of Design
Reuse of Processes
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation17
Reuse of content (principle of topic granularity)Reuse of content (principle of topic granularity)
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation18
What is a book?A book as a collection of topics
Part I Part II Part III
Chapter 1 overview
Chapter 2 overview
Chapter 3 overview
Chapter 4 overview
Chapter 5 overview
Chapter 6 overview
Topic A
Topic B
Topic C
Topic A
Topic B
Topic C
Topic A
Topic B
Topic C
Topic A
Topic B
Topic C
Topic A
Topic B
Topic C
Topic A
Topic B
Topic C
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation19
Reuse of content
Reuse flows from the topic-based paradigm If content is authored as standalone topics,
• Topics can be reused in different contexts
• Topics from multiple components can be integrated as a solution
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation20
Topics reused in deliverablesTopics reused in deliverablesTopic 1
Topic 4
Topic 2
Topic 3
ƒ Deliverables select topics from a poolƒ Deliverable 1 uses topics 1 and 4ƒ Deliverable 2 uses topics 2 and 4ƒ Neither deliverable uses topic 3
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation21
Working with DITA maps
A DITA map applies context to the topics
Organizes a set of topics in a hierarchy and sequenceDifferent organization for different deliverables — not just different formats for the
same content
Can reuse the same topic with different collections of topics
Can provide multiple views on the same topics: by product, by task, …
Sets properties of the topic at a position within the hierarchyProperties include the title and metadata
Change the title relative to the parent topic
Metadata can identify a topic as advanced for one deliverable and basic for another
Eclipse help
JavaHelp
HTMLHelp
web pages
books
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation22
Integrated Instructions for Creating a Web Store Front
Serving the catalogto customers
Creating the database catalog
Managing the system
Designing the system
Messaging notifications
Component Instructions
Integrated solution view: Web Store example
Integrate custom information
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation23
Web-browser view / information center view
Task
Concept
Reference
Online View
Multiple Product
Task 1 Task 2 Task 3
Concept 1 Concept 2 Concept 3
Reference 1 Reference 2 Reference 3
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation24
Reuse of design (principle of specialization)Reuse of design (principle of specialization)
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation25
Reuse of design
General types are rarely enough• Requirements specific to organization or industry
• tasks may span both usage and problem determination
Meet requirements with new elements• New element specializes existing element
• New content is a subset of base content
Add only the deltas - still use the base
Designs are modular• For instance, optional b and i highlighting
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation26
Specializing from Topic to Task
Small DTD additions to enforce document structure.
May have no CSS or XSL process changes.
topic
title
prolog
metadata
related-links
body
task
title
prolog
metadata
taskbody
prereq
context
steps
taskxmp
result
postreq
step
cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?
related-links
topic
title
prolog
metadata
related-links
body
task
title
prolog
metadata
taskbody
prereq
context
steps
example
result
postreq
step
cmd, (info | substeps | tutorialinfo | stepxmp| choices|choicetable)*, stepresult?
related-links
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation27
From Task to Business Task
Additional structure changes.
businesstask
title
prolog
metadata
related-links
btaskbody
prereq
context
bsteps
example
result
postreq
step
appstep
appdesc
task
title
prolog
metadata
taskbody
prereq
context
steps
taskxmp
result
postreq
step
cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?
related-links
task
title
prolog
metadata
taskbody
prereq
context
steps
example
result
postreq
step
cmd, (info | substeps | tutorialinfo | stepxmp| choices|choicetable)*, stepresult?
related-links
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation28
Specializations from Topic
Java APIs C++ APIs
Topic
Concept TaskReference
minitask bctaskmanpages UI help APIs Messages
Java APIs C++ APIs
Topic
Concept TaskReference
minitask bctaskmanpages UI help APIs Messages
Topic is the core.
Each specialization is a delta in design, and if it needs special processing that's a delta too.
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation29
Benefit of design reuse through specialization
No need to reinvent the base vocabulary - Create a module in 1/2 day with 10 lines vs. 6 months with 100s of lines; automatically pick up changes to the base
No impact from other designs that customize for different purposes - Avoid enormous, kitchen-sink vocabularies; Plug in the modules for your requirements
Interoperability at the base type - Guaranteed reversion from special to base
Reusable type hierarchies - Share understanding of information across groups, saving time and presenting a consistent picture to customers
Output tailored to customers and information - More specific search, filtering, and reuse that is designed for your customers and information, not just the common denominator
Consistency - Both with base standards and within your information set
Learning support for new writers - Instead of learning standard markup plus specific ways to apply the markup, writers get specific markup with guidelines built in
Explicit support of different product architectural requirements - Requirements of different products and architectures can be supported and enforced, rather than suggested and monitored by editorial staff
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation30
Reuse of processes (principle of specialization)Reuse of processes (principle of specialization)
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation31
Reuse of processes
Base processing is in extensible XSLT
Overrides provide class-like inheritance of processes
• Standard processing can be customized as needed
• New elements can be given specific behaviors
Processes for base elements apply to new specialized elements by default
• Can rely on base processing, but
• Can write new/custom processing if needed
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation32
task
title
prolog
metadata
taskbody
prereq
context
steps
taskxmp
result
postreq
step
cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?
related-links
task
title
prolog
metadata
taskbody
prereq
context
steps
example
result
postreq
step
cmd, (info | substeps | tutorialinfo | stepxmp| choices|choicetable)*, stepresult?
related-links
task
title
prolog
metadata
taskbody
prereq
context
steps
taskxmp
result
postreq
step
cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?
related-links
task
title
prolog
metadata
taskbody
prereq
context
steps
example
result
postreq
step
cmd, (info | substeps | tutorialinfo | stepxmp| choices|choicetable)*, stepresult?
related-links
Produce information without “steps”, just numbered list
Produce PDF document with “steps”
Create a wizard to lead user through steps of a task
Automatically performAutomatically validate
Produce information web with “steps”
XSLTDITA TaskPossible Outputs
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation33
Specialized processes handle the delta for specialized topic types
Basetopic
Task
Concept
Reference
bcTask
bcReference
Specialization-specific processors
Base processors
Base and delta DTDs Base and delta processors
Specialized processesSpecialized processes
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation34
Summary of reuse
Reuse content through topics• Author content as standalone information
• Reuse topics as components
Reuse designs through specialization• Meet requirements specific to your organization
• Keep interoperability with others
Reuse processing• Inherit base and intermediate processes
• Customize new specialization only as needed
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation35
Summary Benefits and Problems Solved
Development challenges met• Shorter development cycles
• Eliminate variability in HTML outputs
• Support componentization of products and need for reuse
Deliver solution information, not product information• Integration of information
Information glut• More meaningful information (role & task based)
Out-of-date information in books• Updating and maintaining information
Reduce cost of deployment of information• Provide information on-line
Reduce support costs• Customize and update information
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation36
DITA and the Open Community
Making the design open - DITA at OASIS• OASIS TC has excellent participation by vendors, consultants, implementers, users
• Conducted a series of briefings for members, interested guests
• TC chartered to draft first specification toward end of summer
• DTDs and schemas in toolkit are the "reference implementation"
• DITA at OASIS http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
• DITA resources on “OASIS Cover Page” - http://xml.coverpages.org/dita.html
Making the code open• Initially published through IBM developerWorks for mindshare and validation
• Built a community of tool users based on a freely available toolkit
• Will continue to be enhanced as a usable production system and demo of DITA capabilities
• Evaluating priorities for what is needed in the Open Source community
OASIS – Organization for the Advancement of Structured Information Standards
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation37
Thank you! Time for questions…
IBM Corporate User Technology
An Introduction to DITA © 2004 IBM Corporation
DITA topic example<task id="installstorage"> <title>Installing a hard drive</title> <shortdesc>You open the box and insert the drive.</shortdesc> <prolog><metadata> <audience type="administrator"/> <keywords> <indexterm>hard drive</indexterm> <indexterm>disk drive</indexterm> </keywords> </metadata></prolog> <taskbody> <steps> <step><cmd>Unscrew the cover.</cmd> <stepresult>The drive bay is exposed.</stepresult> </step> <step><cmd>Insert the drive into the drive bay.</cmd> <info>If you feel resistance, try another angle.</info> </step> </steps> </taskbody> <related-links> <link href="formatstorage.dita"/> <link href="installmemory.dita"/> </related-links></task>
Identifier, title, and shortdesc
Properties of the topic
Type-specific content body
Relationships to other topics
IBM Corporate User Technology
An Introduction to DITA © 2004 IBM Corporation
DITA map example<map title="Tasks"> <topichead navtitle="Installing" audience="admin"> <topicmeta> <shortdesc>Install products before configuring or using them.</shortdesc> <topicmeta> <topicref href="installstorage.dita"> <topicref href="unscrewcover.dita"/> <topicref href="insertdrive.dita"/> <topicref href="replacecover.dita"/> </topicref> <topicref href="installwebserver.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> <topicref href="installdb.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> </topichead> …</map>
A heading doesn’t have to have a topic
Title and properties can be assigned in the map
A topic can appear multiple times in the hierarchy
The map organizes a set of topics in a hierarchy
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation41
DocBook and DITA
DocBook starts with a fairly comprehensive idea of what a book is, and has a sub-setting scheme for selecting specific parts out of that
Provides mature, standard solution for linear texts such as technical books and articles
Good single sourcing, good interoperability, multiple outputs
An element set refined carefully over a decade, recognition as a standard, and an active open-source community.
Good for users who want to author in the book model
DITA starts with a very constrained idea of what a chunk is, and then has a specialization scheme for describing more kinds of content and constraints
Granularity makes repurposing much easier; plugged into user interfaces, stored in a database and rendered individually on demand, and so on.
Specialization brings the benefits of object-oriented design to information typing
DITA markup encourages the author to focus on reuse