TechWhirl's DITA articles and resources are brought to you by easyDITA. Learn more about their product & sign-up for a free trial at easydita.com.
Although DITA is a fantastic infrastructure for content in a digital age, DITA tools are…well, where the heck are they? Putting your content in XML ought to allow you to do really cool things with your content because it’s no longer tied to format. In essence, having your content in XML makes it available to be handled programmatically in a way that’s just not possible in unstructured content (FrameMaker or Word).
However, up until now, there’s been a great dearth of tools that leverage DITA to the maximum. Even CCMS vendors are falling down on the job a bit, often limiting themselves to being the storage solution and little more.
But now (I’m so excited), there is a company that is filling this great void: Samalander. They make DITA tools, which they call modules, that run on their (free) Software Center. Your content can be stored either locally or within select CCMSs—their tools work either way. It’s built right and the price is fantastic—well within reach for very small writing teams. It’s certainly cheaper than purchasing a CCMS, which, by the way, doesn’t provide this functionality anyhow.
The DITA XREF Manager ($339 CAD as of December 2013) is the one that caught my eye because it works with one of the DITA best practices: keys.
The DITA XREF Manager is the coolest little tool I’ve encountered recently. Think of it as a central spot to manage all of your cross references (internal or external to your DITA map) and all of your keys.
If you have a URL that changes, you use Samalander’s tool to change it in one spot. If you need to apply a key, you don’t have to hunt through maps for the right key name anymore, you just use DITA XREF Manager to see what’s available and pick the right one. Samalander’s tool makes DITA just that much easier.
Cross Reference Management
For cross references, it’s like a link checker, but smarter—and it lets you update your DITA topics right from inside the interface. You can use it to:
- find an existing cross reference in your content (and see the file that has the cross reference)
- see how many times that cross reference is used throughout your doc set
- see if the target of that cross reference exists (publicly accessible website or a topic in your doc set)
- update that cross reference in all locations by typing a URL or browsing to a file (backing up your files for you just in case)
To say it makes working with cross references easier is a gross understatement.
Key management is my favorite part of this tool. I’ve never seen anything that even attempts to manage all your keys from one place. From inside Samalander’s Software Center, you can:
- find existing keys (see which files are referencing them)
- see if one or more keys are unresolved (you have a typo)
- modify a keyref (no typos possible)
- create and apply a new key
- change a cross reference into a key
If you’re working with keys at all, you should really buy this little tool just to save yourself some time. The central management of keys will ensure it pays for itself in author time, never mind troubleshooting time. Work with keys in one spot and never have a typo. XML editors tend to get confused when you have keys in a map that does not directly reference your topic. This little tool is not so easily confused—it handled my glossary keys (in a glossary sub-map) without any problems.
Change Cross Reference to Key Reference
The best feature of all is that you can convert a cross reference into a key reference with the push of a button. So if you’re trying to apply best practices, moving from cross references to key references, this tool makes it simple and idiot proof. It also saves you from having to troll through all your hundreds or thousands of topics.
In all, Samalander’s DITA XREF Manager is well worth the price. It centralizes working with any sort of reference, making it easy to find, modify, and troubleshoot your cross references and keys. Even better, the guys at Samalander who create the software are smart and ready to work with you to make the tool exactly what you need.
I, for one, have already added it to my arsenal of DITA tools.
This article and all TechWhirl articles on DITA are brought to you by easyDITA, the all-in-one DITA authoring and content management solution at easydita.com.