Increase your DITA literacy with The DITA Style Guide

Alan Pringle / News2 Comments

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.

Sign up for updates on The DITA Style Guide

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> 
to continue.</cmd>
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:


<topicref href="foo.xml">

<topicmeta>

<linktext>Replacement text</linktext>

</topicmeta>

</topicref>

______________________

 

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.

About the Author

Alan Pringle

Twitter

Content strategy consulting. Publishing (electronic and print). Eating (preferably pastries and chocolate). COO at Scriptorium.

2 Comments on “Increase your DITA literacy with The DITA Style Guide”

  1. I disagree with the recommendation to use uicontrol when describing keys and userinput when the user must provide input. I think it depends on the rendering convention. If I want to distinguish between text that a user types, (Type 1234)) and actions the user performs on the user interface (click the Configuration link) I would want to use different elements for the two types of input.

  2. You’ve raised an interesting point, Stephanie, which nicely illustrates the need for a DITA style guide. One of the benefits of DITA is interchangability; that is, I can contribute topics to your manual without the need for you to rework anything I’ve done. BUT, that will only work if we have used the DITA elements the same way. Without consistency, interchange is not possible.

    Consistency is arguably more important than correctness in areas such as spelling. I may spell the word “centre” that you spell as “center”. Neither is correct, but using both in the same document is definitely incorrect. Inconsistency erodes authority.

    Any two technical writers may differ on whether something should be or , or or . Using the elements consistently is vitally important, and a style guide, whether it is wrong or right, at least provides a consistency benchmark.

    Having said that, in thinking about vs , I have focussed on the semantics, and not on any rendering convention. Semantically, if a machine has buttons and levers and switches for the user to control the machine, those things are user interface controls. If a string of text needs to be typed into a field, semantically that is user input. The style guide suggests that a key on a keyboard is semantically a control used to interface with the machine. Therefore, if the user needs to press the key marked “Tab”, it is logically identical to a user clicking a button on the screen marked “Next”. Both should be . However, if the user is asked to type some text, that is .

    On reflection, in the last example provided, the “then Tab to continue” should be “then Tab to continue. I will change that in the masters! Thanks for the great discussion!

Leave a Reply

Your email address will not be published. Required fields are marked *