Freedom Through Restriction – How eliminating unnecessary DITA element choices helps writers

Home/Publications/Best Practices Newsletter/2016 – Best Practices Newsletter/Freedom Through Restriction – How eliminating unnecessary DITA element choices helps writers

CIDM

October 2016


Freedom Through Restriction
How eliminating unnecessary DITA element choices helps writers


CIDMIconNewsletter Bob Thomas, Independent Consultant

DITA does a fantastic job of incorporating technical writing semantics into an XML structured authoring environment—but this semantic richness comes at a cost. The large number of elements available at any point can make it challenging to select the best element for your content. Even if you know exactly which element you want, you still need to find it among all of the elements that you don’t want. This practice becomes particularly frustrating when you realize that nearly half of the choices you are sifting through are ones that you would never pick under any circumstances.

Having needless element choices is annoying, but does it have other implications? Yes. Here are some of the consequences: difficult element selection, inconsistent element selection, and wrong element choices. The combination of these impediments reduces productivity and writer satisfaction. To understand why, let’s take a closer look at each of the consequences.

Element selection is a distraction. The more effort you spend selecting an element, the further away you wander from your true purpose. Eliminating unnecessary choices from element selection shortens the amount of time you have to spend away from the thoughts you are developing in your writing. Quick element selection preserves the creative momentum you have developed.

When there are two or more equivalent ways to tag content, it becomes difficult to stay consistent. For instance, out-of-the-box DITA allows you to place a note at the same level as a paragraph, and it also allows you to place a note within a paragraph. Which one is best? Suppose your writing group decides that notes must always be at the same level as a paragraph. Can you remember to do this while you are deep in thought about the content that you are creating? Wouldn’t it be better if the DTD simply disallowed note inside of paragraph? That way, you wouldn’t have to worry about such minutia while you’re writing.

To understand wrong element selection, let’s consider a scenario. Suppose that you are part of a writing team that is documenting system messages. You have correctly chosen to use <msgblock> within <section> to contain the <msgnum> and <msgph> for each of the messages that you are documenting. Unfortunately, your coworker has simply entered several <msgnum> and <msgph> pairs right under <section> without bothering to place them within a <msgblock>. He had the right idea when he used <msgnum> and <msgph>, but wouldn’t it be great if the DTD didn’t allow him to do the wrong thing?

Let me introduce a couple of terms. Block-level elements are paragraph, table, figure, and list elements. Inline-level elements are the elements that occur inside of block-level elements; for example: bold, phrase, and cross-reference.

Now let’s consider the <section> element. The content model for <section> not only allows several block-level elements but, it also allows raw text and inline level elements. The people who created the <section> content model understood that when writers use <section> they should be inserting block-level elements rather than text mixed with inline elements. But, because information architects can specialize DITA elements (use an existing DITA element as a basis for defining new elements), DITA’s creators wanted to make the content model for <section> as flexible as possible. Consequently, text and inline elements were included. That’s great news for people who wish to specialize, but it leaves a lot of clutter lying around for somebody who simply wishes to use <section> for writing. Fortunately, the DITA specification provides methods for reducing the clutter.

The DITA constraints mechanism provides a way to restrict the elements that are available inside of an element while staying compatible with the DITA specification. For example, you can use constraints to redefine <section> so that your writers can select only block-level elements. After implementing this constraint, 45 inline elements immediately drop out of the element list that is available inside <section>. You can still use these elements, but only after you open a paragraph to put them in.

DTD configuration allows you to remove inline element categories (domains) that you don’t want. For example, the programming domain contains <apiname>, <codeblock>, <codeph>, <coderef>, <option>, <parml>, <parmname>, <repsep>, <synph>, <syntaxdiagram>, plus several more elements below these. If your writing group documents only machinery, you probably don’t need the programming domain elements in your DTDs. DTD configuration allows you to remove them.

Identifying Element Categories That You Don’t Need

Now that you know DTDs can be configured, how do you decide which element categories to remove? DITA uses a process called element domain specialization to add element categories to DITA. Table 1 lists the element domains that are included with the DITA 1.3 technical content package.

table1

If your writing group isn’t using any of the elements in a particular element domain, consider removing that domain. If you are using at least one element from an element domain, you should keep that element domain. The xml-mention domain requires the markup-domain to be present.

It is also possible to create an element domain constraint that removes particular elements from an element domain. Suppose you want only <xmlelement> and <xmlatt> from the xml-mention domain. You could create an element domain constraint for xml-mention that removes the other five elements.

Identifying Which Elements to Constrain

An earlier example showed that you could dramatically reduce the element choices in the <section> element by applying a constraint that removes mixed content and limits element choices to block-level elements.  (Mixed content is where you can mix text with inline-level elements.) Besides <section>, several other elements have content models where both block-level elements and mixed content are allowed. This makes them excellent candidates for constraints. Here is a list of DITA 1.3 technical content elements that have both block-level elements and mixed content: <abstract>, <chdesc>, <chdeschd>, <choice>, <choption>, <choptionhd>, <context>, <dd>, <desc>, <entry>, <example>, <info>, <itemgroup>, <li>, <linkinfo>, <lq>, <note>, <postreq>, <prereq>, <propdesc>, <refsyn>, <result>, <section>, <sectiondiv>, <stentry>, <stepresult>, <steps-informal>, <stepsection>, <steptroubleshooting>, <stepxmp>, <tasktroubleshooting>, and <tutorialinfo>.

Implementing Configuration and Constraints

The ideal time to implement a restricted DITA authoring environment is before you migrate to DITA. But what if you’ve been using DITA for a while and have thousands of topics? A couple of options are available. 1) You could begin using the restricted authoring topics for new work without touching your existing content. Most DITA environments will accommodate the old and the new at the same time. However, you may need to convert some library topics to the new restricted topics due to limitations with conrefs. 2) You could convert all of your existing topics to the new restricted authoring topics using conversion programming.

Regrettably, configuring and constraining DITA can be complicated. DTD configuration requires basic skills with DTD syntax. Defining constraints and integrating them into DTDs requires intermediate to advanced skills with DTD syntax. In both cases, familiarity with the DITA Specification’s DTD coding rules is required. Don’t despair. Help is available.

Remember that the advantages of restricting DITA for authoring are worth the effort.

At CIDM’s 2016 CMS/DITA North America conference, I presented an open source DITA Open Toolkit plugin that I created to simplify the DTD configuration and constraints definition process. You can get the plugin from GitHub at https://github.com/robertnthomas/Tagsmiths-Authoring. The skill level needed to deploy and option the authoring plugin is considerably less than modifying the DTDs by yourself.

Benefits

Constraints and DTD configuration let you create a restricted authoring environment so that writers do not have to sift through unwanted choices. Writing becomes more focused and low-level housekeeping chores are eliminated. As unwanted choices drop out, element selection lists reveal the salient semantics of information types. Eliminating arbitrary differences in element structure makes it easier for writers to collaborate.

Having a restricted authoring environment means that your DITA style guide can be shorter. Your new constrained DTDs will not require documentation nor editorial enforcement. Your writing group gets consistent results and your writers are freed from complying with several annoying requirements.

The impact of restriction is significant for all writers, but none more so than writers who are first learning DITA. These writers are typically confused about which element to select. Paring down the list of choices helps them become productive in less time. They will naturally make better choices. This practice will reduce rework on their first efforts, build confidence, and help them be more satisfied with writing in DITA. These advantages are especially important for DITA migration scenarios.

Writer acceptance can make or break a migration to DITA. Their first impressions writing in DITA can set their long-term attitude. Creating a restricted authoring environment is just as important for writer acceptance as is the editing tool you select. Time, thought, and effort spent in restricting DITA will pay dividends right from the start, and it may make the difference on whether a migration succeeds. CIDMIconNewsletter

About the Author

bob-thomas

Bob Thomas
Independent Consultant

Bob Thomas is an independent consultant who is a voting member and an active contributor to the DITA technical committee. Bob was a senior technical writer with AT&T for 15 years. He has spent the past 20 years designing and implementing XML publishing systems, the past 10 have which have been spent exclusively on DITA.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close