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

2. Content reuse in DITA 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

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

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

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

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

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

8. 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  Clever trick: Use the search path file to switch to a different common file for different outputs

9. 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 ( ) are the easiest elements to reuse, in almost any context

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

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

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

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

14. Content reuse in DITA 14 Demonstration: conditionality in DITA

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

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

17. 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  My product Set build-time filters to build customized output Eventually, set run-time filters to display customized output

18. Content reuse in DITA 18 Demonstration: filtering in DITA

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

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

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

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

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