Bitesize DITA

Bitesize DITA: Managing variable content – conditions and more…

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: Conditions – oh what a tangled web we weave

Bitesize DITA is written by Rachel Johnston, Mekon. This month 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 […]

Bitesize DITA: Keys part 4 – scoped keys

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 […]

Bitesize DITA: Keys part 3 – @conref vs @conkeyref

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 […]

Bitesize DITA: Keys part 2 – using keys to manage links

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 […]

Bitesize DITA: Keys part 1 – the basic principles

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 […]

Bitesize DITA: Glossaries: a closer look

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: […]

Bitesize DITA: Glossaries 101

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 […]

Bitesize DITA: Relationship tables – what are they good for?

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 […]

Bitesize DITA: The <fig> element

Not quite. The purpose of the <img> is to house the image itself – referred by href, keyref or both (if the keyref can’t be resolved, the Open Toolkit can use an href as fallback so that you don’t end up with a blank space). The <fig> element is meant to hold the image itself, […]