While doing some DITA training recently for a client I ran across an idea that struck me as being a good way to avoid spaghetti code. In retrospect, it’s one of those obvious “why didn’t I think of that?” ideas: a specialized topic just for holding conref-able text. But first, I ought to explain why this strikes me as being a good idea.
What is Spaghetti Code?
DITA is all about reuse. There’s potentially reuse at three levels: map, topic and sub-topic. At the map level it is easy to take a “chaptermap” from an existing ditamap and republish that as a separate document. Topics can easily be repurposed in new documents. Within topics, the conref mechanism is designed to share content at the paragraph or phrase level. There are two potential problems with using conrefs however: a writer may change (either deliberately or inadvertently) the content of a conref target directly, or the change is made to content which happens to be within a nested conref target. In both cases the change is propagated to whatever topics are referencing them, and unless you using an XML editor that can resolve conrefs in a target, you may not be aware that a change has been made until you look at your output. This is how spaghetti code develops: multiple layers of conrefs point to various topics contained in multiple maps. It gets increasingly hard to manage over time and should be avoided.
When you have spaghetti DITA conref-ed code, writers begin to get overly cautious about making changes to existing topics if they are unable to easily check the dependencies of the content of that topic on other topics that are conref-ing it. (This is why it is good to have a CCMS capable of checking topic dependencies).
Spaghetti code in DITA is a well-known issue: it is talked about in the “Content Reuse” chapter in the excellent DITA Best Practices book, and I attended an excellent presentation hosted by Jang Graat at the last DITA North America conference I was at that talked about the same issue. The solution they suggest is both simple and straightforward: don’t create spaghetti code in the first place. You do this by making sure that you keep all of your conref-able content in separate topics and maps that will not be published. This way all of the conref point one-way to these topics only and spaghetti DITA code does not develop with your conrefs.
The model this sets up is clear and elegant: simply create maps that contain all of the content that you intend to conref. If you are an Information Architect (or a “Documentation Architect“) find all of the content that gets reused in this manner and construct maps containing topics containing only reusable content. When new content is created and it is likely that it will be reused in future versions of a document, those new sections are added to the conref-only target topics in the conref-able map.
The additional twist to this strategy that I recently ran across was to create a specialized topic type for holding these conref-able target content topics. This helps to ensure that they can hold any type of content from the other topic types for reuse anywhere. It’s a terrific idea, since you gain extra flexibility with the conref-able content that can be stuffed into the topic, which can be used in any of the other main topic types.
The first instance I ran across of this idea was in a recent version of the Ixiasoft DITA CMS in a deployment done for a client. It turns out that it is a re-implementation of an idea that goes back at least to 2006 when it was introduced as the
ditacomponent.dtd within the XMetaL XML editor. In the implementation I saw it was put into a new topic type called reusable-content. The purpose of both of these is to have a separate topic type whose content cannot be directly published, and whose sole purpose is to be a repository for reusable conref-ed content. There are a couple of potential drawbacks: since it is not standard DITA some tweaking may be required when it comes to ensuring that output works smoothly, and if sharing content with other firms/organizations is paramount, you will need to ensure that your exported DITA files are “flattened” when it comes to their conrefs (i.e. conref-ed content is contained directly in the exported topic instead of as a conref). Still, it strikes me as being a good idea and one ripe for inclusion in a future DITA specification. It seems like the idea was considered way back when, but was nixed as it was seen as “enforcing a particular best practice for managing reuse“. Still, I think it would be nice to have it as available option that was also part of the standard DITA spec. It certainly makes a lot of sense to use this approach for any new implementation of DITA, as technical writers need to think and plan for sub-topic reuse rather than leaving it wide open, which so often results in spaghetti code.
Anything that gets authors to actively plan and write for sub-topic reuse is a good idea. I don’t know about you, but I prefer my spaghetti on a plate with tomato sauce, not in my code.