Implementing Content Reuse in DITA: The Nuts and Bolts

1. Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne UTS Technical Team Lead IBM Silicon Valley Lab

2. Agenda • Effective reuse of information • Barriers to reuse • DITA designed for reuse • Reuse problems and solutions • Element-level reuse • Conditional reuse • Topic-level reuse • Map-level reuse Content reuse in DITA

3. Effective reuse of information—why we aren’t there yet • Duplicate maintenance of information is expensive • Authoring time • Maintenance! • Consistency • Boilerplate reuse a general practice for non-technical content • Effective reuse of technical content remains elusive Content reuse in DITA

4. Barriers to reuse • Unstructured authoring technologies are unsuitable for reuse • Even structured authoring technologies (SGML) throw up many obstacles • Team communication issues. The smaller the scope, the easier. • Inconsistent and contradictory use of conditionality and other attributes • Information too thoroughly imbedded in a hierarchy • Information is written in a larger context, such as a chapter • How to break out reusable chunks? • Linking issues • What do you link to? • How do you maintain hard-coded links? • External dependencies • Entities of all kinds • Book-metaphor structures Content reuse in DITA

5. DITA is designed to enable reuse • Information design • Modular topics are complete in themselves • Typed topics promote consistency of information coverage • Technical design • Elimination of most external dependencies, with improved management of the dependencies that remain • Flexible link management through ditamaps eliminates hard-coding of links Content reuse in DITA

6. Reuse problems and solutions • Based on reuse experience from the IBM Information Management community • Needs • Technical solutions • Best practices Content reuse in DITA

7. Element-level reuse • Problem: Teams need to reuse information at the most granular level (paragraphs, phrases, notes) • In SGML, we created text entities for this sort of information • !ENTITY prodname “Name of the product this week” • Worked well at the book and library level, but was a disaster when integrating information across product boundaries. Content reuse in DITA

8. DITA solution: content referencing • Any element can be a pointer to another element in another file by using the conref attribute • The reference includes a relative pathname if needed • <ph conref="../reuse/common.dita#common/ prodname/> • Clever trick: Use the search path file to switch to a different common file for different outputs Content reuse in DITA

9. Content referencing best practices • Content referencing outside the file creates an external dependency. Any element in any file can reference any matching element in any other file—spaghetti code! • To simplify dependencies, create a single mixed/combination topic for all reusable information in your information set • Use a combination topic because it will allow you to create as many of the typed topics as you need, all in one location • Give the combination topic an obvious name • You must include the content referencing topic in your ditamap. But set it to toc=no, print=no, and linking=none so it never appears to the end users • Typing in the full conref string is error-prone. Use linking tools in your editor or create macros to insert the content references • Phrases (<ph>) are the easiest elements to reuse, in almost any context Content reuse in DITA

10. Demonstration: element-level reuse Content reuse in DITA

11. Conditionality • Problem: Near-identical information can be used in multiple situations. • Solution: Conditional coding • Problem: Need to differentiate conditions in the output • Solution: Conditional coding with flagging Content reuse in DITA

12. DITA and conditionality • Basic conditional coding is the same for DITA as for other SGML and XML • Restriction: no Boolean logic for conditions; can include multiple conditions, but relationship is a simple OR • Multiple axes of conditionality available • Audience, platform, product, and otherprops attributes • Filtering metadata also at the topic level (more later) Content reuse in DITA

13. Conditionality inside topics • Audience, platform, product, and otherprops attributes available • No fixed values • Best practice: use same values as filtering elements • Best practice: use semantically useful values • In run-time ditaval file, can set each value to include, exclude, or flag • The default is include • Best practice: teams should share values • Best practice: check your spelling! The system will not tell you when you have an undefined value • Flag associates an image with the value • Best practice: use multiple ditaval files with semantically useful names Content reuse in DITA

14. Demonstration: conditionality in DITA Content reuse in DITA

15. Topic-level reuse • Problem: entire topics need to be reused in different venues • Solution 1: include the topic in multiple ditamaps • Solution 2: include the topic in multiple ditamaps, but activate filtering • Solution 3: reuse the topic inside a combination topic Content reuse in DITA

16. Reusing a topic in multiple ditamaps • This is the whole point of ditamaps and modular topics • A topic can be inserted in any ditamap as long as the pathing is clear • Simple relative paths are best, but the system can handle more complex situations with search paths • Verify that conditions and revisions are consistently defined • External dependencies need to be accommodated • Reuse files need to be inserted in the ditamap as well • Inline links may break • Best practice: never code inline links (use maps and relationship tables for all linking except to known external targets) • Graphics are handled by reference, so make sure they are available as well Content reuse in DITA

17. Include topics in multiple ditamaps with filtering • If the topics need to vary depending on their context, include filtering in the metadata • Metadata can be in the topic prolog or the ditamap • Best practice: always one or the other, never both. Experience suggests that the topic prolog is best overall • Audience element includes • Experiencelevel, job, otherjob, type, othertype, name • <audience experiencelevel=“expert” job=“troubleshooting” type=“programmer” • Use “otherjob” and “othertype” to create your own labels • Prodinfo element includes sub-elements • <prodinfo><prodname>My product</prodname> <vrmlist><vrm modification=“2” release=“3” version=“5.0</vrm></vrmlist></prodinfo> • Set build-time filters to build customized output • Eventually, set run-time filters to display customized output Content reuse in DITA

18. Demonstration: filtering in DITA Content reuse in DITA

19. Imbed topics inside combination topics • A mixed/combination topic can contain any number or combination of any other topic types in any order • A combination topic is output as a single XHTML page • The title is the title of the first topic in the set • Caveat: users may not know to scroll through a long combination topic • Topics can be authored exclusively in combination topics, but more often are pulled into special-purpose combination topics to serve a dual purpose • Tutorial example • Useful tip: if you have information that needs to be broken up into multiple topics of different types, create a combination topic and create new topics in it as needed. Then save each topic out to a separate file. Content reuse in DITA

20. Demonstration: combination topic with reused topics Content reuse in DITA

21. Map-level reuse • The highest level of reuse is achieved through architecting and reusing entire maps • Any number of maps can be imbedded in a map • Pathing is the only real technical issue. It’s best to have a central repository where all the maps and topics will come together • The hard part is information design • Set map scope at appropriate levels • “book” level maps are too high a scope • “chapter” level maps work better • Relationship tables can cross scope boundaries • Design maps according to the information design • Each map should represent a distinct point in the navigation • An information architect should manage the top levels of the map Content reuse in DITA

22. Demonstration: map-level reuse Content reuse in DITA

23. Summary • DITA solves or eases many of the technical problems associated with reuse • Element-level reuse • Conditionality • Topic-level reuse • Map-level reuse • Communication between teams remains critical • Good information design is the most important aspect of all Content reuse in DITA