First reuse opportunity leads to more questions

Another of our writers is beginning a project using DITA. Immediately, the opportunity to reuse a section from a reference topic in my user guide presented itself. Should we create a conref link to the section or split each section into its own topic? The advice from our consultant is to try things out. With experience we will figure out what works best for us. This requires a degree of collaboration that we are not accustomed to. Like remembering to update one's status in Facebook or to write a blog post, these are habits we need to develop.

Separating the reference topic into multiple smaller reference topics at first seemed the best way to go. From experience I have learned that multiple conrefs quickly complicates the whole process of producing a manual or help system. On second thought, I think it may be possible to identify one or more general DITAmaps to contain fragments of information to which a conref can be made. Even though the CMS has a powerful search capability, it still seems prudent to organize commonly-used material for easy access.

This leads me to think more deeply about the use of reference topics. They are designed for documenting software language syntax, but lend themselves to a variety of uses. The section structure begs for more than one section per reference topic. My desire to use short descriptions also implies that a single short section is not enough material for a reference topic. It may be that the best way to reuse the material in a section is to create a conref to it. 

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5