an introduction to darwin information typing architecture: dita
DESCRIPTION
An Introduction to Darwin Information Typing Architecture: DITA. Agenda. History of DITA – Why was DITA developed? Introduction to DITA – What is DITA? Benefits of DITA – Why should you care?. What you will hear. DITA is about making life easier in the realm of technical writing - PowerPoint PPT PresentationTRANSCRIPT
IBM Corporate User Technologies
| February 2004 | © 2004 IBM Corporation
An Introduction to Darwin Information Typing Architecture: DITA
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 need – Historic convergences within IBM
IBM task force on information architecture
Technical writing community focus on Minimalism
W3C development of XML
Trend away from SGML (IBMIDDOC)
Recognized need for alternative• Shorter development cycles • Variability in HTML outputs• Componentization of products• Need for reuse
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 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
Appoint technical / thought lead Recruit community technical leads
• Top of line knowledge
• Top of line passion
Define charter and scope
Extend into areas outside ownership to define boundaries
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• Separate 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 - not specific to needs• Knowledge representation is strongly related to current corporate
culture 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
DITA designed to address trade-offsDITA designed to address trade-offs
What is DITA?What is DITA?
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation12
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 Corporation13
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 Corporation14
The core DITA topic 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 Corporation15
DITA and reuseDITA and reuse
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation16
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 Corporation17
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 contentCan reuse the same topic with different collections of topicsCan 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 metadataChange the title relative to the parent topicMetadata can identify a topic as advanced for one deliverable and basic for another
Eclipse helpJavaHelpHTMLHelpweb pages
books
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation18
Reuse of design
General types are rarely enough• Requirements specific to organization or industry
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 Corporation19
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 Corporation20
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 Corporation21
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 Corporation22
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 Corporation23
Reuse of processes
Base processing in extensible XSLT
Standard processing can be customized• Override standard processing as needed
Processes for base elements apply to new specialized elements by default
• Can use base processing• Can write custom processing if needed
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation24
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 Corporation25
SummarySummary
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation26
Summary of reuse
Reuse content through topics• Author content as standalone information
Reuse designs through specialization• Meet requirements specific to organization
• Keep interoperability with others
Reuse processing• Customize only as needed
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation27
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 Corporation28
Backup Slides
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation29
Epic Editor with DITA Maps
Manage hierarchy
Create new & edit
Preview HTML & PDF
Check out
IBM Corporate User Technologies
Introduction to DITA © 2004 IBM Corporation30
Epic Editor with DITA Topics
Content edit
Common elements
Indexing, linking helpers
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