by Doug Williams
DITA enables you to reuse virtually any element on which you can put an ID, right down to putting IDs on individual letters. But with all great power comes great responsibility.
The DITA authoring environment provides an object-oriented coding language masquerading as a souped-up Microsoft Word interface. Because it is an object-oriented XML coding language, DITA grants you powers of reuse at the map, topic, and element level that exceed most people’s imagination. We have barely scratched the surface of what can be done with semantic tagging in output. But as you discover this capability of reuse, remember: Just because you can do it, doesn’t mean you should. Use the power responsibly, so that you avoid accidentally blowing up the world.
The simplest and often the most powerful form of reuse is at the whole topic level. If you write topics as modular, reusable units, you can achieve a great deal of reuse with a minimal level of complexity. Keep in mind that because objects create dependencies, sometimes a little copying is better than a little reuse, even with DITA. If you want to reuse content inside topics, at the element level, then do so using designated source files (libraries or warehouse topics), so that you can keep the complexity manageable. Make it work for you, not against you.
To use the power of library files most effectively, here are a few rules to live by:
- Create designated library topics in a common shared folder.
- Designate an owner of the library who can act as a gatekeeper, and ensure best practices are followed.
- Library files are not production content files. Never create direct conrefs between publication topics. Doing so easily creates spaghetti code, and it is much easier to change a library file or two than to track down and change multiple publication objects.
- Use metadata (topic name, type, SDL Changes field and metadata fields, and so on) to provide the indexing information to help content developers find content for reuse.
- In libraries as well as topics, richly comment your code. What is obvious to you now may not be obvious 6 months from now. For other content developers, the harm they could create by making changes may not be obvious at all. For example, in a library, put reuse chunks inside a section element with a title element without an ID, so that they provide a context to a developer for finding and using the content. Use draft-comment entries in the reused content itself to note content SMEs, owners, or other metadata relevant for people using the content., and _comment tags for more internal use notes.
- For conrefs, avoid using them with content below the whole element level. Try to bring in chunks of content, not phrase elements. Where you use phrases, as with short descriptions, make them the entire contents of the containing element.
- If you have phrases you must use, such as product names or service names, then by preference do so using indirect referencing (SDL variables, or keys) from reference libraries. It is much easier to create a different reference library that uses the same key IDs with different values for different use cases for a few publications than to manage changes in direct-reference conrefs that apply to an entire set of publications.
- Do not use conditional processing (DITA-OT Ditavals, SDL IshConditions) inside libraries. Preferably, use them at the map file level only. In particular, SDL IshConditions are processing instructions that are not native DITA structure, and that can easily break well-formed DITA XML DTD requirements. If you think you must use conditions, stop and think what you could do with multiple map files instead.
- Avoid inline links in library topics. Every link, xref, or topicref creates a dependency. If that link is invalid in any context where that library is used, even if that link is in a conref not used in your publication, then that link will create a validation error in builds.