IBM User TechnologyNovember 2004 | DITA Specialization © 2004 IBM Corporation Principles of DITA...

IBM User Technology

November 2004 | DITA Specialization © 2004 IBM Corporation

Principles of DITA Specialization:Extending the base

Erik Hennum for IBM User Technology

IBM User Technology

DITA Specialization © 2004 IBM Corporation

Reuse of designReuse of design

IBM User Technology


Reuse of design

General types are rarely enoughRequirements specific to organization or industry

tasks may span both usage and problem determination

Meet requirements with new elementsNew element specializes existing element

New content is a subset of base content

Add only the deltas - still use the base

Designs are modularFor instance, optional b and i highlighting

IBM User Technology


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 User Technology


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


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


related-links

IBM User Technology


Specialization of topic types

Topic

Concept TaskReference

Java APIsJava API C++ APIsC++ API

Topic

Concept TaskReference

bctaskTroubleshootermanpagesCommand APIsAPI MessagesMessage

IBM User Technology


Specialization of domains

Use a domain in any topic typeDefines 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 domainsProgramming 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, …

Task topic type

software domain

UI domain

programming domain

highlighting domain

UI domain

Web UI domain

topic elements

IBM User Technology


Pluggability of specialization modules

To create a document type, you plug in specialization modulesFor 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

Task topic type

financial domain

UI domain

highlighting domain?

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

IBM User Technology


The DITA vision: a platform for collaboration

Retail

Medical Legal

Marketing

Technical

Core

Not just product informationMarketing event announcements or

Development functional specifications

Shared specialization modulesBetween partners and across industry peers

Install the modules you need, assemble the document types, and go

IBM User Technology


Reuse of processesReuse of processes

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

IBM User Technology


task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


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 User Technology


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 User Technology


Summary of reuse

Reuse content through topicsAuthor content as standalone information

Reuse topics as components

Reuse designs through specializationMeet requirements specific to your organization

Keep interoperability with others

Reuse processingInherit base and intermediate processes

Customize new specialization only as needed

IBM User Technology


Specializing an element

topic:<!ELEMENT ol (%li;)+>…<!ATTLIST ol class CDATA "- topic/ol "><!ATTLIST li class CDATA "- topic/li ">

task:<!ELEMENT steps (%step;)+>…<!ATTLIST steps class CDATA "- topic/ol task/steps "><!ATTLIST step class CDATA "- topic/li task/step ">

Class attribute identifies package and ancestry

Base processing applies by default

Specialized content replaces base content

IBM User Technology


Demo

Take it away, maestro

IBM User TechnologyNovember 2004 | DITA Specialization © 2004 IBM Corporation Principles of DITA...

Documents

Transcript of IBM User TechnologyNovember 2004 | DITA Specialization © 2004 IBM Corporation Principles of DITA...