Transcript DITA Specialization Direction

IBM User Technology
Principles of DITA Specialization:
Extending the base
Erik Hennum for IBM User Technology
November 2004 | DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Reuse of design
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
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
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Specializing from Topic to Task
topic
task
title
title
prolog
prolog
metadata
metadata
body
taskbody
related-links
related-links
Small DTD additions to
enforce document structure.
May have no CSS or XSL
process changes.
DITA Specialization
prereq
result
context
taskxmp
example
steps
postreq
step
cmd,
cmd,
(info
(info
| substeps
| substeps
| tutorialinfo
| tutorialinfo
| stepxmp
|
|xmp
choices|choicetable)*,
| choices)*, result? stepresult?
© 2004 IBM Corporation
IBM User Technology
From Task to Business Task
task
businesstask
title
title
prolog
prolog
metadata
Additional
structure
changes.
metadata
taskbody
btaskbody
related-links
related-links
prereq
result
prereq
result
context
taskxmp
example
context
example
steps
postreq
bsteps
postreq
step
cmd,
cmd,
(info
(info
| substeps
| substeps
| tutorialinfo
| tutorialinfo
| stepxmp
|
|xmp
choices|choicetable)*,
| choices)*, result? stepresult?
DITA Specialization
step
appstep
appdesc
© 2004 IBM Corporation
IBM User Technology
Specialization of topic types
Topic
Reference
Task
Concept
Troubleshooter
bctask
manpages
Command
APIs
API
Java
JavaAPIs
API
DITA Specialization
Messages
Message
C++
C++APIs
API
© 2004 IBM Corporation
IBM User Technology
Specialization of domains
topic elements
Task topic type
software domain
programming domain
UI domain
UI domain
highlighting domain

Web UI domain
Use a domain in any topic type
Defines the semantics of discourse or metadata properties for a subject area
Extend any existing domain or the discourse or metadata elements in the base topic

DITA core domains
Programming domain for programming names and text: apiname, codeph, …
Software domain for software names and text: cmdname, filepath, varname, …
UI domain for user interface names and text: wintitle, uicontrol, …
Highlighting domain for formatted text: b, i, …
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Pluggability of specialization modules
Task topic type
financial domain
UI domain
?
highlighting domain
 To create a document type, you plug in specialization modules
For financial services software, you might include
The task type
The UI domain
A new domain that you specialized for the vocabulary of the financial industry
The highlighting domain – if you are a pragmatist
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
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
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
The DITA vision: a platform for collaboration
 Not just product information
Marketing event announcements or
Development functional specifications
 Shared specialization modules
Between partners and across industry peers
Install the modules you need, assemble the
document types, and go
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Reuse of processes
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
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
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
XSLT
DITA Task
Possible Outputs
Produce information
without “steps”, just
numbered list
task
title
Produce information
web with “steps”
prolog
metadata
Produce PDF
document with
“steps”
taskbody
related-links
prereq
result
context
taskxmp
example
steps
postreq
Create a wizard to
lead user through
steps of a task
step
cmd,
cmd,
(info
(info
| substeps
| substeps
| tutorialinfo
| tutorialinfo
| stepxmp
|
|xmp
choices|choicetable)*,
| choices)*, result? stepresult?
DITA Specialization
Automatically perform
Automatically validate
© 2004 IBM Corporation
IBM User Technology
Specialized processes
Specialized processes handle the delta for specialized topic types
Base and delta DTDs
Base and delta processors
Base
topic
Base processors
Task
bcTask
Concept
Specialization-specific
processors
Reference
bcReference
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
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
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Specializing an element
topic:
<!ELEMENT ol
…
<!ATTLIST ol
<!ATTLIST li
(%li;)+>
class CDATA "- topic/ol ">
class CDATA "- topic/li ">
Specialized content replaces
base content
task:
<!ELEMENT steps
…
<!ATTLIST steps
<!ATTLIST step
(%step;)+>
class
class
CDATA "- topic/ol task/steps ">
CDATA "- topic/li task/step ">
Class attribute identifies
package and ancestry
Base processing applies by
default
DITA Specialization
© 2004 IBM Corporation
IBM User Technology
Demo
 Take it away, maestro
DITA Specialization
© 2004 IBM Corporation