What’s new, cool, useful and powerful in DITA. Learn DITA best practices.


What happens when source content is bloated? DITA, minimalism, and agile development.
DITA, minimalism, and agile content

Helping Writers Succeed with Great DITA, Minimalism, and Agile Content

Too often, when we work on a DITA implementation we spend a lot of time on the bells and whistles of our CMS or the DITA-OT publishing scripts. But, often the content is bloated, uses unsemantic markup, is riddled with duplication, and suffers from condition overload. If this is the case, you won’t get the benefits. Bottom line: DITA, minimalism, and agile development are powered by robust, semantically correct DITA content.

It’s not just that you won’t be getting all the benefits. Having messy content sets up your writers for failure and frustration.

The meals are pretty poor but then they never use fresh ingredients – garbage in, garbage out.

DITA isn’t delivering as promised. Garbage in, garbage out certainly applies to the DITA-OT.

Remove/Edit/Repair/Prune (RERP) Bloated Content

Remove/Edit/Repair/Prune (RERP) redundant hyper-conditionalized content with lots of duplication and arbitrary differences in the content is absolutely needed to realize the benefits of DITA.

With bloated non-semantic content you will be unable to achieve your business goals (faster turnaround, faster translation, lower translation cost, fewer errors, more reuse, etc.).

Are technical writers the best agents of change for DITA, minimalism, and agile content?

How much can you rely on writers/editors deeply embedded in the product teams to be the blunt destroyers of duplication that we so much need?

In general (and there are always exceptions), the greater the portion of the remove/repair/prune burden that we impose on writers/editors, the lower will be the benefits.

In other words:

↑ Reliance on embedded writers → ↓ RERP benefits:

↓ Slower migration

↓ Ability to support reuse

↑ Frustration and conflict with product teams

↑ Frustration for writers and editors

↑ Translation costs

↑Turnaround time

Why tech writers embedded in the product team may not be the best DITA change agents

The more that we rely on embedded writers to get great DITA, minimalism, and agile content, the more disappointed we will be in the results. This is true for a few reasons, including:

We are humans, and we have relationships. When we RERP we will be brutally pruning the content of our colleagues, people that want to like us. Each degree that the RERP team is removed from the content owners, the easier it will be to be brutally effective.

Deconstructing someone else’s work is much easier than deconstructing your own. (This is why publishers have editors!)

Embedded writers will need time to scale up to the required new skill sets (minimalism, conref’ing, applying conditions within reused items where possible, creating reusable chunks in content banks, applying semantic markup, and more). The greater the share of RERP on embedded writers, the smaller will be the benefit and the longer the delays. (When a dedicated team handles RERP, each team does not have to repeat rookie mistakes. Roughly translated folk expression: you don’t have to learn how to shave on your own cheeks.)

Change is hard. Big change is harder. There are lots of talented writers on your team. Some of them will get with the program out of the gate. Most of them will require time. By reducing what we ask of individual writers, we can get them to the desired skill levels and new mindset faster.

So, what is the alternative?

For RERP, here is a proposal: FreezeRERPThawEnhance

  1. Selected Content Freeze – Content is selected for RERP, it is frozen. (For example, from Thursday to Monday – or any two or three work day period.) During the freeze, no changes may be made to the content by writers.
  2. Selected Content RERP –dedicated RERP team. During this period, they may ask questions of the content owners.
  3. Selected Content Thaw –CMS expert (or content owner or dedicated RERP team) returns or uploads the content to the CMS. Makes sure that duplicate content is archived or removed.
  4. Content Enhancements –with the new content in the CMS, writers seek further advantages/efficiency gains:, more paring down, referring to newly created conrefs, etc.

I would love to hear your experiences and thoughts! Click here to learn more about how many ideas to put in single DITA topic.

 

How to add a DITA specialization to oXygen Editor or oXygen Author

Congratulations. You just got your brand new DITA specialization. And, you want to use it.  Follow these instructions to successfully integrate your DITA Specialization to oXygen Editor or oXygen Author.

These instructions apply when the DITA specialization is available as a DITA Open Toolkit plugin. Read more

Including equations in DITA content

By Jakobswiki (Own work) [CC BY 3.0 (http://creativecommons.org/licenses/by/3.0)], via Wikimedia Commons

Sample Butler volmer equation. What DITA elements would you use to display this equation?

There are three possible containers for equations in the equation domain: equation-inline, equation-block, and equation-figure. Choose the DITA elements that makes the most sense for your equations: inline, in a separate block, and/or an equation or series of equation with a caption. Read more

Should you use tables in DITA?

By Byzantinischer Maler um 1020 [Public domain], via Wikimedia Commons

This table is from the year 1020. It’s time to consider smarter ways of building and maintaining tables.

Writers are conditioned to using tables. We are creatures of habit, and using tables in DITA seems to come naturally if you are used to writing in Word or FrameMaker.

Bottom line: When you need to present information that will be table-like when read, your default preference should be for definition lists.

We know that you are comfortable using tables. And you love merging cells and doing all the cool stuff that oXygen Author and XMetaL Author can help you do with DITA tables. Get past it. Consider using definition lists wherever possible. Read more

How to describe choices in a DITA task topic?

Duncan Lilly [CC BY-SA 2.0 (http://creativecommons.org/licenses/by-sa/2.0)], via Wikimedia Commons

When the reader needs to make a decision, use the correct DITA element.

Why use <choices> or <choicetables> instead of <ol> or <ul> in a task topic when you need to choose what to do next? DITA markup offers different options for describing choices in a DITA task topic.

The benefit of <choices> or <choicetables> is that the markup is semantic! When you use <choices> or <choicetables>, the machine (and the writer!) understands explicitly what you are talking about. Read more

Polygamous or Monogamous DITA Topics?

DITA topics should focus on one idea

Keep your DITA topics focused. One topic. One idea.

Embedding multiple topics inside one topic file (polygamous topics) is not good practice. We call these topics, “polygamous topics”. If, in real life, polygamy tends to be a really bad idea, the same is true for DITA topics.

The golden rule for DITA topics is Read more

How to organize a bookmap: nesting under the element

How you organize a bookmap will affect how easy or difficult it will be for you to maintain and update your content. Should you nest a DITA map under the <chapter> element in a bookmap, or should you nest topics directly under the <chapter> element? Read more

Nest DITA topics under a topic or under a topichead?

nesting DITA maps and DITA topics

For the red-footed booby (Sula sula) nesting comes naturally. For DITA projects, nesting topics and maps requires some forethought and planning

When you have a collection of DITA topics to nest, or individual DITA topics to next, you have a lot of choices. Often, too many choices. In a ditamap, you can nest DITA topics under a topic, <topichead> or <topicgroup>. In a bookmap, you can nest DITA topics or a ditamap under the <part> or <chapter> element. Read more

Group topics in DITA maps

Referring to DITA maps from a bookmap or from another DITA map provides a great way for grouping topics. You can refer to the DITA map in the bookmap, or in a parent ditamap, whenever you want to include the collection of topics in the bookmap.

Tip: Read more

DITA Bookmaps or regular DITA maps?

Bookmaps enable users to organize their DITA information into front matter, parts, chapters, and back matter. Typically, publications are created from a bookmap while DITA maps are used for Read more