DITA on your Local Disk: The "Common" Concept
This series of articles explores the how and why of using DITA XML in the file system: in the early stages of DITA adoption it saves you time and money. You cannot afford to not use DITA.
This article explains how introducing a "Common" directory solves many DITA link management problems. It also explains one serious problem with a "Common" directory, bad XREFs and CONREFs, and how to manage and fix such problems.
Back to "DITA on your Local Disk"
- Contents
Why a "Common" Directory?
A "Common" directory is a standard location to place reusable content: topics, tasks, reference, and concept topics. "Common" is a repository of reusable content.
But "Common" can be much more than just a repository of reusable content. It can be an easy way to accomplish what is generally considered to be a function restricted to complex Component Content Management Systems (CCMS's) or Content Management Systems (CMS's): link management. It just depends on how you understand "repository" and "metadata". In this article we look at "Common" as a repository with controlled linking. In the article, Metadata, the File System and "Common", we'll look at metadata.
"Common" and Consistent Relative Paths
The idea of using a "Common" directory in the file system solves most of the problems associated with maintaining links in your DITA files by making it easy for authors to find information: if your file system organization is consistent the links will have consistent relative paths. Consider the following graphic:
There are several advantages to this structure:
- The file system is easier for authors to understand.
- It delivers many of the benefits of a CCMS or CMS while avoiding the overhead costs, especially training and support.
- CONREFs to information in either common folder will all have a consistent relative path from a specific product file. This makes managing links much easier.
- All common information is stored in a predictable location. For the author, this makes finding information for importing with CONREFs much easier.
- Notice that in this graphic there are two "Common" folders. You can have any number of "Common" folders depending on the business rules that apply to the information in each one. In this example we have release-dependent and release-independent information in separate "Common" folders.
Consistent relative paths and easy to find content for CONREFs is already more than half the battle in making reuse easy for authors. It also solves many linking problems in DITA files but not all. You also have to have some rules that apply to common directories and the DITA files inside them.
Rules in "Common": No XREFs or CONREFs within "Common"
The rules that must be applied in a "Common" directory are required because you cannot predict what the context will be for most of the DITA in a "Common" directory. If a DITA file in "Common" has an XREF to another DITA file in "Common", can we be sure that both files will be present in any particular information product? If the target of the XREF is missing, then the link will be broken. Because of this problem we need a rule that says we have to restrict linking within a "Common" directory.
The real source of the problem is usually legacy content. In the early stages of a transition to DITA documents are converted to DITA, often as whole chapters of a legacy book. Authors may then find sub-topics in two or more of these chapter files that could be CONREF'd into the chapter, thus increasing reuse and reducing maintenance.
However, in creating the CONREF target file, an author may copy a topic from a chapter file into a new CONREF'able file. If the author also copies links in that new CONREF'able DITA file, the links are almost certain to break completely or in some of the contexts the file is CONREF'd into.
So, the rule to make linking work when you use a "Common" directory has to be XREFs and CONREFs are not allowed in "Common".
The following graphic illustrates the problem with links within "Common".
Samalander RESTRICTED Linking Parameter
The Samalander Sanity Checker Pro module allows you to select "Restricted Linking" directories such as "Common" in its configuration file. If you declare "Common" to be a restricted linking directory Sanity Checker Pro will report any CONREF or XREF between files in "Common" as an error.
This is a very important feature for managing links in DITA files in your file system. It is especially important since this kind of error is very common in normal editing, can be almost impossible to detect and fix manually, and will persist no matter how much training the author receives. Copy and paste is just too ingrained in our work habits to expect that an author with looming deadlines will be able to avoid making this mistake.
Fortunately Sanity Checker Pro and Link Fixer are all you need to manage and correct bad links within "Common" or anywhere else for that matter.
Summary
This has explained how introducing a "Common" directory solves many link management problems and enhances writer satisfaction and productivity by making reuse easier and more consistent.
This article has also explored:
- the linking rules that need to be applied to a "Common" directory,
- why they are needed,
- where these linking problems come from, and
- how to manage and fix them with the Samalander Sanity Checker Pro module and the Samalander Link Fixer module.
The next article, Metadata, the File System and "Common", will explore the concept of "Common" and "metadata" in greater detail, including how writers use them to increase reuse all on their own, with little or no training.