Update July 30, 2014: Download the EPUB edition of The DITA Style Guide for free. The print edition is no longer available.
To help technical communicators get a grasp on all the elements and attributes in DITA, Scriptorium Press will publish The DITA Style Guide: Best Practices for Authors by Tony Self, founder of Hyperwrite and chairperson of the OASIS DITA Help Subcommittee. We plan to release printed and electronic book (ePub) versions this fall.
Whether you’re evaluating DITA, just getting started, or are already creating content, this book will help you figure out the best uses for the elements and attributes in the DITA structure. Speaking from personal experience, I wish I had this book years ago. Trying to determine when to use which element isn’t as straightforward as you’d think, especially when you’re new to DITA. Although the DITA language specification is helpful, it provides little background or context about the reasons for using particular elements (and frankly, it makes for dry reading).
That’s where Tony’s book comes to the rescue. The DITA Style Guide will offer practical information and real-world examples, as shown in the following excerpts:
What Element for Keystrokes?
The uicontrol element should be used when describing keys on a keyboard, and the userinput element for describing keystrokes that the user must input. …
It is not immediately obvious in DITA what element should be used to mark up keyboard keys, such as Enter, Ctrl and Backspace. The best approach (without resorting to specialization) is to use the uicontrol and userinput elements, depending on context.
When describing keys on a computer keyboard, use the uicontrol element. For example:
<p>Use the <uicontrol>Tab<uicontrol> to move from field to field.</p>Note: Do not use the shortcut element; this element is intended to identify keyboard shortcuts in descriptions of user interface controls in windowed applications.
When describing a series of keystrokes that the user must input, use the userinput element. For example:
<cmd>Enter <userinput>1234</userinput>, then <userinput>Tab</userinput>Link Text for Relationship Tables
To control the text displayed in links automatically generated from the relationship table, a linktext element must be added to the topicmeta for the topicref.
If you want the link generated by a reltable to have a different title from the linked topic itself, you may think the technique would be to use a navtitle attribute in the topicref element. However, that doesn’t work.
The technique to use is to add a topicmeta element to the topicref, and include a linktext element containing the name of the link text. The example below shows the technique:
The printed book will be available from online bookstores all over the world, and the electronic book will be distributed through Scriptorium’s online store and other electronic book retailers.
Sign up if you want to receive emailed updates about the book’s status and release date. We’ll send you occasional messages about the book, and you’ll also get exclusive sneak peeks at content and a chance to win a free copy when the book released.