400 likes | 730 Views
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
E N D
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 • 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
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
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
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
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
DITA designed to address trade-offs What is DITA?
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
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
topic concept reference task The core DITA topic types – The “IT” in DITA A unit of information which is meaningful when it stands alone. Provides background information that users need to know. Provides procedural details such as step-by-step instructions. Provides quick access to facts.
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
Working with DITA maps Eclipse help JavaHelp HTMLHelp web pages books • A DITA map applies context to the topics • Organizes a set of topics in a hierarchy and sequence Different 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 hierarchy Properties 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
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
Specializing from Topic to Task topic topic task task title title title title prolog prolog prolog prolog metadata metadata metadata metadata body body taskbody taskbody related related - - links links related related - - links links prereq prereq result result context context example taskxmp Small DTD additions to enforce document structure. May have no CSS or XSL process changes. postreq postreq steps steps step step cmd, (info | substeps | tutorialinfo | stepxmp cmd, (info | substeps | tutorialinfo | xmp | choices)*, result? | choices|choicetable)*, stepresult?
task task title title prolog prolog metadata metadata taskbody taskbody related related - - links links prereq prereq result result context context example taskxmp postreq postreq steps steps step step cmd, (info | substeps | tutorialinfo | stepxmp cmd, (info | substeps | tutorialinfo | | choices|choicetable)*, stepresult? xmp | choices)*, result? From Task to Business Task businesstask Additional structure changes. title prolog metadata btaskbody related-links prereq result context example postreq bsteps step appstep appdesc
Specializations from Topic Topic is the core. Each specialization is a delta in design, and if it needs special processing that's a delta too.
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
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
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
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
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
Epic Editor with DITA Maps Manage hierarchy Create new & edit Preview HTML & PDF Check out
Epic Editor with DITA Topics Content edit Common elements Indexing, linking helpers
DITA topic example Identifier, title, and shortdesc <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> Properties of the topic Type-specific content body Relationships to other topics
A heading doesn’t have to have a topic 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> Title and properties can be assigned in the map The map organizes a set of topics in a hierarchy A topic can appear multiple times in the hierarchy