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

Related posts


March 18. 2013 22:24


I generally propose the actual to say I 'm novice by means of weblog and here surplus beloved the internet site . Almost all prepared Im planing to bookmark about the internet site. You unquestionably have outstriping well crafted written content . Bless the undertaking on the part of divvying alert through us the web site doc .

vigrx plus reviews

March 19. 2013 03:24


I primarily suggest typically the to say I 'm novice to weblog and already superfluous dear the real website. A lot of inclined Im planing to bookmark onto the internet site. You unquestionably have outperforming well written information . Sanctify the project on the part of divvying alert if you use us the online presence insurance.

discount vigrx plus

June 14. 2013 18:07


Truly i am rattling aim after publicised the article in this site. It has lot of historic things. I necessary to cognize whatsoever different things from this collection.

South Beach Smoke

June 17. 2013 08:52


Nice article, Its really informative for me, I want to share this in my social network.I agree with much of everything you said; but more importantly, the topic of your article was an area of long interest to me which made the whole thing a little more fun and enjoyable for me.

Central Coast Air Conditioning

August 2. 2013 16:10


I have to admit that I have never heard about this information I have noticed many new facts for me. Thanks a lot for sharing this useful and attractive information and I will be waiting for other interesting posts from you in the nearest future.keep it up

Home page

Comments are closed