IBM User Technologies DITA Specialization Why When and

IBM User Technologies The roadmap for this session Why do we need specialization? When should we specialize? How do we implement a specialization? How do we manage the specialization process? How do we design a specialization? An extended example– the API Reference 2 September 2005 © 2005 IBM Corporation

IBM User Technologies Why do we need specialization? Consistency and clarity for special content

IBM User Technologies Customization and collaboration The realization Generic XML solutions are not specific to your needs Knowledge representation is strongly related to industry, community, and organization culture The customization tradeoff Making an XML markup more useful for your needs means more cost and effort shared with fewer people The specialization alternative By specializing, you can share processing and content with others at your level of design commonality 4 September 2005 © 2005 IBM Corporation

IBM User Technologies Before DITA – consistency through guidelines <topic id="install. Ant"> <title>Installing Ant</title> 1. 6. 3 Writing a procedure <shortdesc>Before using Ant. . . <body> 1. 6. 3. 1 Create a section for each action the <section> user should take. <title>Download step</title> <p>You go to the Apache The web title of the section should summarize. . . the action. <section> <title>Environment step</title> The first paragraph in each section should <p>You set the JAVA_HOME. . . describe what the user does. . . . With guidelines for a general markup: Consistency depends on editorial vigilance Mistakes will be made Processes depending on the guidelines are fragile A “ghost” markup visible only to people familiar with the guidelines 5 September 2005 © 2005 IBM Corporation

IBM User Technologies Different guidelines for different teams <topic id="install. Ant"> <title>Installing Ant</title> <topic id="install. Ant"> <shortdesc>Before using Ant. . . <title>Installing Ant</title> <body> <shortdesc>Before using Ant. . . <section> <body> <title>Download step</title><ol> <p>You go to the Apache web <li>Go to the Apache web site. . <p>You select your platform. . . <section>. . . <title>Environment step</title> <li>Set the JAVA_HOME, ANT_HOME, . . . <p>You set the JAVA_HOME. . . <p>On Windows, you use the. . Different guidelines mean: Different formats for content Varying completeness of detail Problems for integration 6 September 2005 Emphasis on technical edits Multiple processes with multiplied resource demands © 2005 IBM Corporation

IBM User Technologies What the markup indicates General: how the text is structured Specialized: what the text means <topic id="install. Ant"> <title>Installing Ant</title> <task id="install. Ant"> <shortdesc>Before using Ant. . . <title>Installing Ant</title> <body> <shortdesc>Before using Ant. . . <ol> <taskbody> <li>Go to the Apache web. . . <steps> <p>You select your. . . <step><cmd>Go to the Apache web. . . <stepinfo>You select your. . . <li>Set the JAVA_HOME, . . . <p>On Windows, you use. . . <step><cmd>Set the JAVA_HOME, . . . <stepinfo>On Windows, you use. . . The specialized markup: Guides the writer to create more complete and precise content Enforces consistency across organizations Makes the content easier to understand, validate, and process 7 September 2005 © 2005 IBM Corporation

IBM User Technologies Better processing for precisely defined content Method Summary Formatting in many ways For instance, summary output and detail output Navigation across content Method Detail From summary to detail From citation to definition 8 September 2005 © 2005 IBM Corporation

IBM User Technologies When should we specialize? When the content conforms to a special

IBM User Technologies Criteria for specialization Your content has a formal, consistent definition You are creating guidelines to require a pattern More specific than existing information types More restrictions on structure More specific semantics You can commit to design, implement, and maintain the specialization The benefit of having the specialization outweighs the cost of creating the specialization 10 September 2005 © 2005 IBM Corporation

IBM User Technologies DITA at Nokia EXTERNAL DOCUMENTATION Sales User Guide Package (paper, PDF, HTML) Interactive Tutorial Quick Guide (simulation) (paper, PDF, Support HTML) Easy Guide documentation (HTML) for dealers (paper, Online Help simulation) Marketing material Service Documentation (paper, multimedia) (paper, PDF, HTML, video) INTERNAL DOCUMENTATION Software Specifications Test Specifications User Interface Specifications 11 September 2005 © 2005 IBM Corporation

IBM User Technologies Surviving old information types Fallback processing When to discard Keep the valid content The specialization breaks, and Revert to a more general information type Process as general content Apply new information types as you maintain the content set Continually evolve to meet new challenges no one will fix it The content is phased out – The floppy disk vocabulary domain? Your Information Architecture changes The information type becomes limiting or no longer worth maintaining – Word. Star command information type? New technological subject areas – An ecogrid? New strategies for informing users – Reminders? 12 September 2005 © 2005 IBM Corporation

IBM User Technologies How do we implement a specialization? Substitute new elements for existing

IBM User Technologies Extension by substitution General topic Specialized task <topic id="installstorage"> <task id="installstorage"> <title>Installing a hard drive</title> <body> <taskbody> <ol> <steps> <li><ph>Unscrew the cover. </ph> <step><cmd>Unscrew the cover. </cmd> <itemgroup>The drive bay. . . </itemgroup> <stepresult>The drive. . . </stepresult> </li> </step> <li><ph>Insert the drive. . . </ph><step><cmd>Insert the drive. . . </cmd> <itemgroup>If you feel. . . </itemgroup> <info>If you feel resistance. . . </info> </step> </ol> </steps> </body> </taskbody> </topic> </task> Substituting specialized elements for base elements Declares more precise semantics Enforces more constrained content models 14 September 2005 © 2005 IBM Corporation

IBM User Technologies Specialized instances are also base instances Topic instances Task instances (also topic instances) Design constraint – strict extension by substitution Every specialized content model must be a subset of the base content model Thus, any specialized instance is guaranteed valid for the base markup Design discipline – designers accept the constraints to get the benefits 15 September 2005 © 2005 IBM Corporation

IBM User Technologies Specialization rules Design constraint – substitution of restricted content models Any change where every instance is valid for the base after restoring the base names A specialized topic can make optional <shortdesc> required, specialized, or dropped Similarly, the optional platform attribute can be required, enumerated, or dropped A good fit for discourse because text tends toward loose content models Declare the specialization ancestry with the class attribute in the schema DTD: XSD: <!ATTLIST steps class CDATA "- topic/ol task/steps "> <xs: attribute ref="class" default="- topic/ol task/steps "/> The ol element in the topic module is the base of the steps element in the task module Process by matching the element type in the class attribute XSLT: <xsl: template match="*[contains(@class, ' topic/ol ')]"> Specializations can rely on the base processing or override. 16 September 2005 © 2005 IBM Corporation

IBM User Technologies Implementing a specialized <steps> element topic design module: <!ELEMENT ol (%li; )+>. . . <!ATTLIST ol class CDATA "- topic/ol "> <!ATTLIST li class CDATA "- topic/li "> task design module: <!ELEMENT steps (%step; )+>. . . <!ATTLIST steps class CDATA "- topic/ol task/steps "> <!ATTLIST step class CDATA "- topic/li task/step "> topic processing module: <xsl: template match="*[contains(@class, ' topic/ol ')]">. . . task processing module: <xsl: template match="*[contains(@class, ' task/steps ')]">. . . 17 September 2005 Every element has an architectural class attribute The class attribute identifies the module and type ancestry Base processing applies by default The specialization can override base processing © 2005 IBM Corporation

IBM User Technologies Overriding the base processing Base processing topic processing module: <xsl: template match="*[contains(@class, ' topic/ol ')]"> <ol class="ordered. List"> <xsl: apply-templates/> </ol> </task> Override for the specializations task processing module: <xsl: template match="*[contains(@class, ' task/steps ')]"> <hr class="steps. Start"/> <p>You perform the following actions: </p> <xsl: apply-imports/> <hr class="steps. End"/> </task> 18 September 2005 Insert the base processing © 2005 IBM Corporation

IBM User Technologies Generalizing – casting to the base type Task our common types My. Task my organization’s content your organization’s processes Cast the content from specialized to general types A standard transform generalizes instances – reverts the names To send content to someone who doesn’t have your specialized markup To retire the specialized markup but keep the content 19 September 2005 © 2005 IBM Corporation

IBM User Technologies Specialization for DITA topic types The fundamental content objects Topic Concept Task Learning assessment Reference or Use case specification Tutorial Command API C++ API 20 September 2005 Message or. . . Java API © 2005 IBM Corporation

IBM User Technologies Domains for vocabulary common to many topics ph uicontrol formfield DITA core domains programming: software: user interface: highlighted phrases: apiname, codeph, codeblock, . . . cmdname, filepath, varname, . . . wintitle, uicontrol, . . . b, i, u, sup, sub, . . . Create new domains for the content specific to new subject areas The metadata properties, names, or text structures for a subject area Telco, Semiconductor, Financial, Insurance, Retail, Legal, Life Sciences, … 21 September 2005 © 2005 IBM Corporation

IBM User Technologies Pluggability of specialization modules Task topic type Financial domain Financial services task document type UI domain ? Highlighting domain To create a document type, you plug in specialization modules Like blades in a Swiss Army knife For financial services, the document type might include The task type The UI domain A new domain that you created for the vocabulary of the financial industry The highlighting domain – if you are a pragmatist 22 September 2005 © 2005 IBM Corporation

IBM User Technologies Instances of DITA domain phrases in a topic type <task id="amortizingloan"> <title>Amortizing the loan</title>. . . <taskbody> <steps> <step><cmd>Choose the Amortizer menu item</cmd> <stepresult>The < wintitle>Amortizer</wintitle> window displays. </stepresult> </step> <step><cmd>Enter the <loanfactor>term</loanfactor>. </cmd> <info>You <b>must</b> choose one of the options. </info> </steps> </taskbody> </task> 23 September 2005 UI domain Financial domain (possible future) Highlighting domain © 2005 IBM Corporation

IBM User Technologies Specializing DITA maps how-to role task reference task Define information structures composed of many topics Specialize the context where a topic appears Specify the role that a topic takes on in the context Require a specific type of topic in the context Special kinds of maps For instance, the bookmap specialization has preface and chapter roles Domains that extend different kinds of maps A domain module can provide a constent structure for sets of topics that appear in many kinds of maps For instance, the how-to domain requires one or more task topics 24 September 2005 © 2005 IBM Corporation

IBM User Technologies Example of a map specialization Role assigned to a topic of any type <!ELEMENT howto ((%topicmeta; )? , (%conceptref; )*, ((%taskref; ), (%exampleref; )? )+, (%summaryref; ))> <!ATTLIST howto href CDATA #REQUIRED Required structure for. . . > the contained topics. . . <!ELEMENT taskref ((%topicmeta; )? , (%taskref; )*)> <!ATTLIST taskref href CDATA #REQUIRED type CDATA "task" Required type for the. . . > referenced topic. . . <!ATTLIST class howto %global-atts; CDATA "+ map/topicref howto/howto "> taskref %global-atts; CDATA "+ map/topicref howto/taskref "> Specialized from topicref 25 September 2005 © 2005 IBM Corporation

IBM User Technologies How do I manage the specialization process? Ensuring breadth of perspective and quality Enlist the people close to the problem in solving the problem 26 September 2005 © 2005 IBM Corporation

IBM User Technologies Checkpoints Initiate Plan Develop Use The phases of specialization development Meet the team requirements for extensibility Meet the community requirements for governance Initiate – Explain your idea to a governance board Plan – Prepare to develop and get agreement from approvers Develop – Implement and validate Use – Distribute, migrate, support, and (possibly) eventually discontinue 27 September 2005 © 2005 IBM Corporation

IBM User Technologies How do we design a specialization? Start by mocking up the standard format for the special content in the base type Think small, referential, and layered 28 September 2005 © 2005 IBM Corporation

IBM User Technologies Design strategy 1 – think small Design smaller topic types with shallow structures Not large documents with deep structures Like legos – build larger structures by aggregating smaller structures For an example, see bookmap Analyze large problems to identify smaller component problems Isolate and solve the smaller component problems Maintain and evolve the smaller designs separately Reuse smaller designs in many combinations For instance, a how to composed of concept, task, and example Apply the lessons of Object-Oriented Design to document design 29 September 2005 © 2005 IBM Corporation

IBM User Technologies Design strategy 2 – think references Refer to a single description instead of copying the content Where several topics talk about the same thing, design to use references to a single topic Single maintenance for authors and authoritative explanation for users For instance, event announcement and whitepaper topics can incorporate the same product summary topic by reference Use specialized maps to define a structure for topics In the specialization, assign a default value to the type attribute Topics of the type or its specializations can plug into the position For instance, a contract structure that requires a warranty topic at the end 30 September 2005 © 2005 IBM Corporation

IBM User Technologies Design strategy 3 – think layers Extension by substitution adds pressure on the designer to anticipate as many specialized uses as possible Specializers can only substitute within the constraints imposed by the base Provide levels of precision In higher layers, provide loose content models and general semantics – support many variations In lower layers, provide specific structure and semantics – including enforcing best practices For instance, the existing DITA Task topic doesn’t allow the section specializations that some organizations need – proposal at the OASIS DITA Technical Committee to add a more general Task parent 31 September 2005 © 2005 IBM Corporation

IBM User Technologies Extended example – the design of API Reference topic types for libraries like Java class libraries Provides guidance and semantics for the specific programming language Work in progress 32 September 2005 © 2005 IBM Corporation

IBM User Technologies API Reference – the abstract topic type Reference api. Ref 33 September 2005 Abstract layer – shared API elements such as a Definition section with Qualifiers and Relations and an Implementation section © 2005 IBM Corporation

IBM User Technologies API Reference – the generic topic types Reference Abstract layer api. Ref api. Package api. Classifier api. Operation api. Value Generic layer – basic API constructs for an interface (adopted from Eclipse e. Core) 34 September 2005 © 2005 IBM Corporation

IBM User Technologies API Reference – language-specific topic types Reference Abstract layer api. Ref api. Package api. Classifier java. Package java. Interface Generic layer 35 September 2005 api. Operation api. Value java. Method java. Field java. Class Language-specific layer – types that model the constructs of an API in the specific language or programming environment (Java, C++, …) © 2005 IBM Corporation

IBM User Technologies API Reference – map structures Base api. Map Expresses flexible assembly of generic API items Includes packages, operations, classifiers, and named values Specialized java. APIMap Enforces Java constraints – a package contains subpackages, classes, and interfaces Declares roles – a class provides error or exception notification API maps included in other maps by conref or map reference Some topics nested inside other topic files Always part of the container – Java methods and fields 36 September 2005 © 2005 IBM Corporation

IBM User Technologies API Reference – domain keywords Base api. Domain Delimits the names of generic API items Whether appearing in API Reference or any other topic Specialized java. APIDomain Delimits the names of Java packages, classes, interfaces, . . . 37 September 2005 © 2005 IBM Corporation

IBM User Technologies High priority topic specializations Concept Glossary Reference API Reference – includes Function Reference Bibliographic Entry Element Reference Example Reference FAQ Message Reference Language Statement Reference – includes Command-Line Reference Task Troubleshooter – related: Maintenance Analysis Procedure Tutorial 38 Topic Context help Learning See article by John Hunt and Robert Bernhard on Developer. Works September 2005 © 2005 IBM Corporation

IBM User Technologies The DITA vision: a platform for collaboration Content markup that’s specific to the subject area Technical Retail Marketing event announcements, Development functional specifications, or Real estate appraisal forms Shared markup modules Core Across industry segments or communities and between partners Medical Legal Local markup for the organization Agree on the shared basics, diverge on the local idiosyncrasies 39 September 2005 © 2005 IBM Corporation

IBM User Technologies Summary Specialization improves on guidelines Easier to write More complete Consistent Specializations is based on strict substitution Supports collaboration by reverting to base types Topics, topic domains, maps, and map domains Design in terms of small content objects Assemble them to represent larger information 40 September 2005 © 2005 IBM Corporation

IBM User Technologies More about DITA Learn about DITA OASIS – http: //www. oasis-open. org/committees/dita Cover pages – http: //xml. coverpages. org/dita. html Talk about DITA Join the dialog on the DITA forum – http: //groups. yahoo. com/group/dita-users/ Download the DITA Open Toolkit http: //sourceforge. net/projects/dita-ot/ 41 September 2005 © 2005 IBM Corporation