intelligent content solutions
In the last two Bitesize DITA articles we’ve been looking at the most common ways to manage variable content, through keys and through conditional filtering. Changes to the DITA 1.3 spec offer us some more sophisticated filtering options that may be useful. Branch filtering enables us to apply more than one DITAVAL file to a […]
Bitesize DITA is written by Rachel Johnston, Mekon. In the previous article, we looked at the problems that over-use, or inappropriate use of conditions and filtering can bring – this time we’re going to explore the thought processes and decisions behind managing variable content. Scenario 1: content that changes unnecessarily Before you think about how […]
Bitesize DITA is written by Rachel Johnston, Mekon. Variation in product names, product families, branding, and functionality across similar manual sets has always been a headache for technical authors. When Help Authoring Tools first featured conditional text it seemed like a godsend. But, when the only tool you have is a hammer, everything looks like […]
Changes to the specification can take time to bed down – as well as the time needed to develop support in CCMSs and authoring tools, there’s an organic process of establishing real use cases and a body of good practice. It’s a bit like musical repertoire – some parts of the spec are equivalent to […]
This time we’re going to look at how indirect referencing works as a mechanism for reuse. But in order to understand indirect addressing for re-use, let’s recap a little about direct referencing. Even if you are new to DITA, you might be aware of the idea of ‘conreffing’ content from one place to another – it’s […]
Technical documentation, traditionally, is heavy on cross references. We often need to refer to other documents in the documentation set, or help the user find other relevant information within a long document. But cross references present us with two problems: What if the target topic moves? How do I make sure the link is still […]
Keys help us to solve two of the problems that make content difficult to manage: Maximising reuse One of the main principles and rationales for DITA is the reuse of content – but in order to do that we sometimes need to take some of the context away from a particular topic such as references […]
We can break down the <glossentry> topic into three main parts: <glossterm> : the term itself <glossdef>: the definition to be paired with the term <glossbody>: supporting information about the definition <glossbody> is a container for a variety of useful elements that you may want to include in your glossary. Here are a few examples: […]
Glossaries are a useful tool – a way of making sure readers can access definitions of specialist terms without having to keep repeating it throughout a publication. But without structured authoring they can be hard to develop and maintain. Just keeping content properly alphabetized and maintaining cross references between terms and definitions can be arduous […]
A novice DITA author’s mental model tends, quite reasonably, to equate the DITAmap with a publication’s TOC, so placing a table in it just seems a strange thing to do. Reltables themselves can be hard for the human eye to ‘parse’ – without careful reading it can be hard to look at a relationship table […]