Overview Of DITA 1 - OASIS
www.oasis-open.orgLearn about the new featuresof DITA 1.3Presented by:The OASIS DITA Technical CommitteeandThe OASIS DITA Adoption Technical Committee1
www.oasis-open.orgWelcomeJoAnn HackosPresident, Comtech Services, Inc.joann.hackos@comtech-serv.comChair, OASIS DITA Adoption TechnicalCommittee Today’s program Our presentersYes, we are recording this presentation.2
www.oasis-open.orgAgenda 3 Welcome – JoAnn HackosIntroduction – Kris EberleinContext Sensitive Help – Stan DohertyBranch Filtering – Robert AndersonKey Scopes – Chris NitchieLearning and Training – Mark MyersRelease Management – Tom CihakDITA Domains – Nancy HarrisonTroubleshooting – Bob ThomasQ&A
www.oasis-open.orgIntroductionKristen James EberleinEberlein Consulting LLCkris@eberleinconsulting.comChair, OASIS DITA Technical Committee Who are we? Where have we been? Where are we going?4
www.oasis-open.orgSo what is the OASIS DITATechnical Committee? 5A group of 16 people whomeet on a telephone calleach week for 60 minutes.We use Robert’s Rules ofOrder, but work byconsensus most of thetime.Some of us have NEVERmet in person We (or our corporateemployers) pay so that wecan participate indeveloping DITA.For most of us, it’s a laborof love
www.oasis-open.orgBackground of DITA releases DITA 1.0 (June 2005) DITA 1.1 (May 2007) 6Information types: Topic, map, concept, task,reference. ditabaseArchitecture: Specialization; conref; map-basedorganization & linkingDomains: Software; user interface; programming;highlighting; utilitiesInformation type: Book map; glossentryArchitecture: Addition of DITAVAL for conditionalprocessing; attribute specializationDomains: xNAL; indexingNew elements: abstract , foreign , data
www.oasis-open.orgBackground of DITA releases(cont.) DITA 1.2 (December 2010) Information types: Architecture: 7Key-based addressing for links and variable textAdditions to conref; constraintsTopic and domain integrationDomains: Learning & Training specializationGeneral task; machinery taskSubject scheme; classification mapClassification; delayed conrefTask requirements; hazard statementNew elements: Many!
www.oasis-open.orgWhat’s coming with DITA 1.3? I’m going to let today’s panelists address thisissue, and then we’ll summarize at the end ofthe Webinar, after the questions.Some invisible changes Improvement to quality of specificationAbility to single source the XML grammar filesImprovement in TC processes and overallreduction of technical debtRelease of the specification in three packages Base Technical content Complete8
www.oasis-open.orgCSH Callback and Display MetadataStanley Doherty, Ph.D.OASIS DITA TC, Help SC, TechComm SCStan@ModularWriting.comMultiple Help TargetsDITA Help SourcesROBUST METADATA FORCSH CALLBACKS ANDTARGET DISPLAYENVIRONMENTS9Big shout-out to Tony Self (HyperWrite Ltd.),Help Subcommittee Chair and Architect of these features
www.oasis-open.orgCSH Callbacks and DisplayProblem statement: We are asked to generate an increasingnumber of user assistance targets from the same DITA obileHelp10
www.oasis-open.orgCSH Callbacks and DisplayProblem statement: We are asked to generate an increasingnumber of user assistance targets from the same DITA sources.If each target form of user assistance requires callback and displaymetadata in some proprietary format(s), we get into trouble if wehave to maintain this metadata apart from our DITA sources.TARGETScallback IDsDITA Help Sourcesdisplay informationcallback IDsdisplay informationcallback IDsdisplay ileHelp
www.oasis-open.orgCSH Callbacks and DisplayProblem statement: We are asked to generate an increasingnumber of user assistance targets from the same DITA sources.If each target form of user assistance requires callback and displaymetadata in some proprietary format(s), we get into trouble if wehave to maintain this metadata apart from our DITA sources.Solution: Extend DITA metadata to support the generation ofmultiple, target-specific callback and display schemes.callback IDsDITA Help Sourcesdisplay informationcallback IDscallback and displaymetadatadisplay informationcallback IDsdisplay anceMobileHelp
www.oasis-open.orgManaging Target-Specific CallbacksDITA 1.313ADDED: Three metadata attributes to resourceid .@appid – Identifies a referenced topic to an external application.@ux-context-string – Specifies a context ID for that topic.@ux-source-priority – Specifies how to resolve conflicts betweencallbacks defined in a map or in a topic.
www.oasis-open.orgManaging Target-Specific CallbacksDITA 1.3ADDED: Three metadata attributes to resourceid .@appid – Identifies a referenced topic to an external application.@ux-context-string – Specifies a context ID for that topic.@ux-source-priority – Specifies how to resolve conflicts betweencallbacks defined in a map or in a topic.DITA Map14 map topicref href "dialog-1.dita"/ topicmeta resourceidappname "ios7a"appid "iphone"ux-content-string "callback 4437"ux-source-priority "map-takes-priority"/ resourceidappname "kitkat"appid "droid"ux-content-string "id#4500"ux-source-priority "map-takes-priority"/ /topicmeta /topicref /map
www.oasis-open.orgManaging Target-Specific CallbacksDITA 1.3ADDED: Three metadata attributes to resourceid .DITA Topic15 topic prolog DITA Map resourceid map appname "kitkat" topicref href "dialog-1.dita"/ appid "droid" topicmeta ux-content-string "id#4501"/ resourceid /prolog appname "ios7a" /topic appid "iphone"ux-content-string "callback 4437"ux-source-priority "map-takes-priority"/ resourceidappname "kitkat"appid "droid"ux-content-string "id#4500"ux-source-priority "map-takes-priority"/ /topicmeta /topicref /map
www.oasis-open.orgManaging Target-Specific CallbacksDITA 1.3ADDED: Three metadata attributes to resourceid .DITA Topic16 topic prolog DITA Map resourceid map appname "kitkat" topicref href "dialog-1.dita"/ appid "droid" topicmeta ux-content-string "id#4501"/ resourceid /prolog appname "ios7a" /topic appid "iphone"ux-content-string "callback 4437"ux-source-priority "map-takes-priority"/ resourceidappname "kitkat"appid "droid"Topic-map conflictux-content-string "id#4500"resolutionux-source-priority "map-takes-priority"/ /topicmeta /topicref /map
www.oasis-open.orgManaging Target Display InformationDITA 1.317ADDED: One map element and one attribute for resourceid . ux-window -- specifies information about a target display.@ux-windowref -- specifies a target display profile for a topic.
www.oasis-open.orgManaging Target Display InformationDITA 1.3ADDED: One map element and one attribute for resourceid . ux-window -- specifies information about a target display.@ux-windowref -- specifies a target display profile for a topic.DITA Map map topicmeta ux-windowid "win47" name "mobile1"top "10" left "20" height "400" width "500"features "status yes,toolbar no,menubar no,location no"relative "true" full-screen "no"/ /topicmeta . . . /map 18
www.oasis-open.orgManaging Target Display InformationDITA 1.3ADDED: One map element and one attribute for resourceid . ux-window -- specifies information about a target display.@ux-windowref -- specifies a target display profile for a topic.DITA Map19 map topicmeta ux-windowid "win47" name "mobile1"top "10" left "20" height "400" width "500"features "status yes,toolbar no,menubar no,location no"relative "true" full-screen "no"/ /topicmeta . . . topicref href "dialog-1.dita"/ topicmeta resourceidappname "ios7a"appid "iphone"ux-content-string "callback 4437"ux-source-priority "map-takes-priority"ux-windowref "mobile1"/ /topicmeta /topicref /map
www.oasis-open.orgBenefits to DITA Help Practitioners Added semantics in DITA maps to define: Added logic to allow writers to manage: 20Multiple target applications consuming callback IDsMultiple target display profilesMultiple contexts or target displays for any topicConflicts between IDs defined in maps and topicsProcessing required to generate target-specific API,mapping, or configuration filesReduced our dependencies on external,dedicated HATs (Help Authoring Tools).
www.oasis-open.orgBranch FilteringRobert Anderson, IBMrobander@us.ibm.com21
www.oasis-open.orgBranch filtering: why? Problem: publication includes a subset ofinformation with unique conditions 22Different sections of a map for different audiencesReused external content with its own conditionsOne section of a map intended for multiple audiencesDITA defines the “DITAVAL” syntax to set filterconditions – but no formal mechanism toassociate unique conditions with portions of apublication (with branches of a map)
www.oasis-open.orgBranch filtering: what? how? New ditavalref element in maps creates a standardmechanism for fine-grained filtering Operates on that branch of the map, and on contentreferenced from that branch topicref href "parent.dita" ditavalref href "conditions.ditaval"/ topicref href "child.dita"/ topicref href "child2.dita" audience "abc"/ topicref href "child3.dita"/ /topicref 23Conditions apply to the map branch itself, as well as tocontent in parent.dita and all three children
www.oasis-open.orgBranch filtering: simple case Use ditavalref as in previous slideConditions apply only to that section; globalfilters still take priorityWhatever is filtered out at higher level, stays out Potential uses: 24For example, global: filter out all but Linux. Branch:filter by Linux variant. Nested branch: filter by version.Reuse of external content with unique conditionsInclude a section that is only relevant to one audience,inside of a more general publication
www.oasis-open.orgBranch filtering: what else? Also allows publishing a single branch of contentmultiple times with distinct filter profilesImagine: 25Product manual with install chapter repeated by OSMarketing guide with sections filtered by regionHomeowner’s how-to book with landscaping chapter filteredby climate or by Homeowner’s Association restrictions
www.oasis-open.orgBranch filtering: advanced case Common content for unique audiences Most of a product manual applies to all audiencesInstall chapter set up for filtering based on audience: Windows/Mac/Linux; desktop vs laptop; imperial vs metric DITA 1.2: publish one guide for each OS, hardware, or regionAlternately, publish many versions, stitch together into one DITA 1.3: topicref href "install.dita" ditavalref href "imperial-units.ditaval"/ ditavalref href "metric-units.ditaval"/ !-- -- /topicref 26
www.oasis-open.orgBranch filtering: advanced sample How did that work exactly? topicref href "install.dita" ditavalref href "imperial-units.ditaval"/ ditavalref href "metric-units.ditaval"/ !-- -- /topicref map continues with other branches 27Install branch published in imperial, then metric.All other branches publish as usual.Imagine if this general presentation,common to this point, could nowinclude samples tailored to each ofyour individual publications
www.oasis-open.orgBranch filtering summaryDITA 1.2:28DITA 1.3:
www.oasis-open.orgKey ScopesChris Nitchie, Oberon cope-1key-1key-2key-3scope-2key-1key-2key-3DITA 1.2 - One definition per keyper publication.29DITA 1.3 - Each scope within apublication has its own definitions.
www.oasis-open.orgKey Scopes – Solutionkeyscope "scopeName" 30Any map or topicref can declare itself thecontainer for a key scope by specifying the@keyscope attribute.Keys defined within a scope can only be directlyreferenced by key references in the same scope,allowing different definitions for differentreferences.Scoped key definitions can be referenced fromoutside their scopes by including the scopename, like this:keyref "scopeName.keyName"
www.oasis-open.orgKey Scopes – Example map topichead keyscope "tractorX" navtitle "Tractor X" topicref keys "oilChart" href "tractorX/oilChart.dita" / topicref href "common/oilChangeProcedure.dita" / /topichead topichead keyscope "tractorY" navtitle "Tractor Y" topicref keys "oilChart" href "tractorY/oilChart.dita" / topicref href "common/oilChangeProcedure.dita" / /topichead /map . And in common/oilChangeProcedure.dita . p For information about the type and amount of oil to use, refer to xref keyref "oilChart" / . /p 31
www.oasis-open.orgKey Scopes – Benefits Fully backwards-compatible with DITA1.2; existing maps will continue to workexactly as they did before. Keyref semantics entirely unchanged. Topic authors do not generally need to beaware of the scope structures of the mapsusing the topic. Simple markup for declaring key scopes.32
www.oasis-open.orgKey Scopes – New Possibilities Key scopes enable use cases that aredifficult or impossible to support in DITA1.2, including: 33Omnibus publications combining standalonemaps with conflicting keys.Multi-product documentation with commonkey names with different meanings in differentparts or chapters (e.g. keyref "introduction").Multi-lingual publications with conkeyrefs tolanguage-specific notes and warnings.
www.oasis-open.orgLearning and Training Updatesin DITA 1.3Mark MyersSAPmark.myers@sap.com34
www.oasis-open.orgNew Feature: Standardize LearningObject and Group Referencing Standardize markup for referencing and storinglearning objects and learning groups as separatefiles in a file system or repository to promote reuseLearning Map 1Learning Map 2Learning Map 3Instructor-Led Training3 DaysVirtual Classroom2 DaysE-Learning1 DayLearning Group 1Learning Group 1aLearning Group 1aLearning Object 1Learning Object 1Learning Object 1Learning Object 2Learning Object 2Learning Object 2Learning Object 3Learning Group 2Learning Group 2Learning Group 3Learning Group 3Learning Group 2Learning Group 4.35.
www.oasis-open.orgStandardize Learning Object and GroupReferencing 36Learning objects and groups are intended to be reusedin multiple mapsDITA 1.2 is not consistent in the way it allows you toreference learning objects, and learning groupsDITA 1.3 addresses this by adding: Two new map refs (LearningObjectMapRef,LearningGroupMapRef) Two new wrapper elements (LearningObjectMap,LearningGroupMap)
www.oasis-open.orgLearning Object DITA 1.2 Example37 Contents of learning object aredefined, and redefined, in eachmap This allows reuse of thecontents of a learning object,but not the learning objectcontainer itself Not ideal for true “object-based”learning object Inefficient and potentially errorproneMain Learning MapVariant Learning Map
www.oasis-open.orgLearning Object DITA 1.3 Example38 In DITA 1.3, you can wrap alearning object withlearningObjectMap Store it as a separate file Then reference it from manymaps using learningObjectMapRef Similar approach can also beused forlearningObjectGroupMapMain Learning MapLearning Object Map
www.oasis-open.orgStandardize Learning Object and GroupReferencing 39Standardize method for referencing learningobjects and groupsEn
Chris Nitchie, Oberon Technologies chris.nitchie@oberontech.com book.ditamap key-1 key-2 . key-3 . key-1 key-2 key-3 book.ditamap key-1 scope-1 key-1 key-2 . key-3 . scope-2 . key-1 key-2 . key-3 . DITA 1.2 -
The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA Technical Committee. The DITA-OT is a set of Java-based, open-source tools and Ant scripts that transform DITA content (maps and topics) into deliverable f
OASIS Darwin Information Typing Architecture (DITA) TC Chair(s): Don Day Editor(s): Michael Priestley Robert D. Anderson JoAnn Hackos Related Work: This specification replaces or supercedes: OASIS DITA Language Specification Version 1.0 This specification is related to: OASIS DITA Architectural S
DITA Architectural Specification v1.0 1.1 approved as an OASIS Standard in August 2007. DITA Language Reference v1.1 DITA Architectural Specification v1.1 1.2 approved as an OASIS Standard in December 2010. DITA Specification v1.2 Current version of
DITA technologist should read, not the average writer or manager. The good news is that we’ve designed DITA 101 for writers and managers. We’ve taken our years of expe rience helping organizations to move to DITA a
According to the DITA Exchange product team, the map viewer is the most frequently accessed UI by SMEs and serves as a popular entryway into topic creation, review, and revision. Technically, the map viewer is not part of the DITA Exchange editor, rather it is part of DITA Exchange’s l
LightWeight DITA seems to be quite promising in improving the spread of DITA outside the . Introduction When studying technical writing, authoring in DITA has become an unavoidable course. . (OASIS) to release it to the public. In fact, IBM realized that it “would be more useful if [it] could actually have this spread to other firms that .
Man y DITA authoring and publishing tools come with standard transformers for most common delivery formats, such as PDF, RTF and HTML. The DITA Open Toolkit, an open source collection of utilities and documentation to help writers work with DITA, includes basic transformers for PDF, RTF, HTML, DocBook, Eclipse Help, and Microsoft HTML Help.
OASIS ODF V1.0 Approved Chair OASIS DITA Submitted WS-Addressing to W3C Contributed UML2 to Eclipse IBM named chair IETF IBM commitment to RF in OASIS Lead OASIS standardization of WS-DM and DITA Pledged 500 patents to Open Source 2006 Web Services Reliabil
