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.