Overview Of DITA 1 - OASIS Open - OASIS Open

Transcription

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 groupsEncourage reuse of learning objects and groupswithin and across organizations and companies

www.oasis-open.orgNew Feature: Improve Learning and TrainingInteractions 40Provide more robust content models forinteraction (assessment) question statements,answer values, and feedback (allows multipleblock elements).Examples (not easily possible in DITA 1.2):

www.oasis-open.orgImprove Learning and Training Interactions 41The available semantic elements in DITA 1.2 inassessment questions, answer values, and feedbackblocks were unnecessarily restrictive.Define two new domains for the Learning and TrainingSpecialization: interactionBase2Domain learning2DomainNew domains provide a base model that allows multiblock element questions, answers, and feedbackNew domains are otherwise semantically identical tothe original domainsOriginal domains are still available

www.oasis-open.orgImprove Learning and Training Interactions 42Enables more robust interaction question statements, answers,and feedbackEnables more engaging assessments, ideal for electroniclearning deliveries like e-learning, mobile learning, and so on

www.oasis-open.orgRelease managementTom Cihak, FreescaleDITA Technical CommunicationsSubcommittee, r65612@freescale.com43

www.oasis-open.orgRelease management: Problem Use case 1: Use case 2: 44Our 2000-page manual is being updated. How can Ialert my existing readers to the significant changes?A regulatory agency requires that we record the dateand time changes are made down to the second.

www.oasis-open.orgRelease management: Solution An optional domain to enable authors to logsignificant changes between document revisions 45Based on bookmap/bookchangehistory.Comments and metadata (release notes) logged in thetopic or map.Elements only—no processing specified. XQuery usedto gather changes.Filtering can be by date and using select attributes,giving users maximum flexibility.

www.oasis-open.orgRelease management: Elements46ElementDescription change-item A single release note change-person Person making change change-organization Agency requiring change change-revisionid ID associated with change change-request-reference Wrapper element change-request-system Tracking system change-request-id ID associated with tracking system change-startedDate change was completed change-completed Date change was completed change-summary Description of change

www.oasis-open.orgRelease management: Example prolog !-- . -- changehistory-list change-item product "productA productB" change-person Tom Cihak /change-person change-completed 2014-03-23 /change-completed change-summary Made change 1 /change-summary /change-item change-item product "productA" change-person Tom Cihak /change-person change-organization JEDEC /change-organization change-completed 2014-06-07 /change-completed change-summary Made change 2 /change-summary /change-item /changehistory-list !-- . -- /prolog 47

www.oasis-open.orgRelease management: Summary Benefit for content workers Benefit for readers Improved accuracy of change reportingMiscellaneous benefits 48Easier logging of changes—no external documentsneededPotentially increased compliance with standards Changes are more likely to be made if it’s easierFacilitates Wikipedia-like tabbed displayRelease notes can be edited

www.oasis-open.orgDITA DomainsNancy HarrisonInfobridge ry, DITA Technical Committee49

www.oasis-open.orgNew domains for DITA 1.3 50Domains define markup for a particular subject area.DITA 1.3 provides a number of new domains: Domains to extend available semantic markup: XML mention Release management (Tom Cihak) Branch filtering (Robert Anderson) Domains that formalize how DITA references nonDITA objects: Mathematics: MathML & Equation domains Graphics: SVG domain

www.oasis-open.orgXML mention Purpose and benefit: A way to mark upmentions of XML syntactic componentssuch as element and attribute. Can be used in the DITA standardDocumentation for XML applicationsTraining materials for XML technologiesExample: p Use the xmlelement uicontrol /xmlelement (userinterface control) element to indicate the names of buttons,entry fields, menu items, or other objects that enable auser to interact with a graphical user interface. /p 51

www.oasis-open.orgMathML & Equation domains Purpose and benefit: Provides containers for equations and anintegration with the MathML standardEnables direct use of MathML markup withinDITA documentsEnables use-by-reference of MathML markupheld in separate non-DITA documentsExample: p A block equation using an image: equation-block id "eq-3.2a" equatio

www.oasis-open.org So what is the OASIS DITA Technical Committee? A group of 16 people who meet on a telephone call each week for 60 minutes. We use Robert’ s Rules of Order, but work by consensus most of the time. Some of us have NEVER met in person We (or our corporate empl