Principles of DITA Specialization: Extending the base

1. Erik Hennum for IBM User Technology Principles of DITA Specialization:Extending the base

2. Reuse of design

3. Reuse of design • General types are rarely enough • Requirements specific to organization or industry • tasks may span both usage and problem determination • 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

4. 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?

5. 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

6. bctask Specialization of topic types Topic Topic Reference Reference Task Task Concept Concept Troubleshooter manpages Command APIs API Messages Message Java APIs Java API C++ APIs C++ API

7. Specialization of domains topic elements Task topic type software domain programming domain UI domain UI domain Web UI domain highlighting domain • Use a domain in any topic type • Defines 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 domains • Programming 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, …

8. Pluggability of specialization modules • To create a document type, you plug in specialization modules • For 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

9. 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

10. The DITA vision: a platform for collaboration • Not just product information • Marketing event announcements or Development functional specifications • Shared specialization modules • Between partners and across industry peers Install the modules you need, assemble the document types, and go

11. Reuse of processes

12. 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

13. Possible Outputs XSLT DITA Task Produce information without “steps”, just numbered list Produce information web with “steps” Produce PDF document with “steps” Create a wizard to lead user through steps of a task Automatically perform Automatically validate

14. 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

15. Summary of reuse • Reuse content through topics • Author content as standalone information • Reuse topics as components • Reuse designs through specialization • Meet requirements specific to your organization • Keep interoperability with others • Reuse processing • Inherit base and intermediate processes • Customize new specialization only as needed

16. 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 "> Specialized content replaces base content Class attribute identifies package and ancestry Base processing applies by default

17. Demo • Take it away, maestro