Confessions of a DITA Virgin: Is Your Formatting Automated?

Dear DITA Virgin,

I’m glad to have found you – yep, I’m a DITA virgin, too. I have a lot of questions about something you said in your last post. You said, “we could write everything in plain, unformatted text – no bold, italics, heading 1, 2, or 3 styles, no indentation, no space before or after paragraphs, no margins –no formatting at all.”Isn’t that going to make all our content look exactly the same?

Formatting is helpful for drawing attention to important sections, organizing information, and making text and images easier to consume. This seems counter-intuitive. Why in the world would you do it this way?

Sincerely,
Formatting Is Good: Hardly Taboo

Dear FIGHT,

Yep, this one confused me at first, too. When we use DITA, we should always keep reuse in mind as a goal. Let me give you an example that would apply to my day-to-day life as a reviewer of contracts and other legal matters.

12.c Entire Agreement. This Agreement contains the entire agreement between the below-signed parties and cancels and replaces any previous written or oral agreements between the parties concerning the subject matter herein. The provisions of this Agreement may be modified, waived, or terminated only upon the written approval of all authorized parties.

I’ve seen language like this in standard contracts (in Word and PDF versions), in software licensing agreements, in online end-user agreements (those multi-page agreements we’ve all accepted without reading), in the warranty section in my DVD player user manual, and on liability releases I’ve signed before rock climbing at the gym. I could imagine that the wording might be exactly the same for that standard clause. But the formatting for each of those uses might be very different.

For instance:

If you’re going to come up with a reuse system that’s truly automated, you have to automate the formatting. Otherwise, your “system” grabs all the building blocks of text together, but a human being still has to open each one of those and apply formatting manually.

Every time there’s a small change to any of the text in any of those documents, the formatting would have to be reapplied. Automating the formatting is a natural “next step” in breaking the content into small chunks. Fortunately, that’s what we do in the DITA world. We create “maps” of all the blocks. The map identifies which blocks go together and in what order. We also identify the formatting requirements for all those blocks.

So, headings can look different from lists, which can look different from body text –and each of those looks different depending on the type of document where the text is used. Yes, this is very different than the way we’ve always done it in Word. Yes, it requires that we approach things differently (for instance, we have to plan much better). We’ll save time when it comes to reusing the content over and over in a variety of different ways.

–The DITA Virgin

• Author
• Recent Posts

Val Swisher

Val Swisher is the Founder and CEO of Content Rules, Inc. Val enjoys helping companies solve complex content problems. She is a well-known expert in content strategy, structured authoring, global content, content development, and terminology management. Val believes content should be easy to read, cost-effective to create and translate, and efficient to manage. Her customers include industry giants such as Google, Cisco, Visa, Facebook, Roche, and IBM. Her fourth book, “The Personalization Paradox: Why Companies Fail (and How to Succeed) at Creating Personalized Experiences at Scale,” was published in 2021 by XML Press.

Val is on the Advisory Board for the Technical Communications Program at the University of North Texas. When not working with customers or students, Val can be found sitting behind her sewing machine working on her latest quilt. She also makes a mean hummus.

Latest posts by Val Swisher (see all)

• How to Make Conferences More Inclusive for the Hard of Hearing Community - December 2, 2024
• Preparing Content for AI: 6 Reasons Why You’re Not Ready - August 29, 2024
• How to Be Inclusive in the Workplace: My Experience as a Hard of Hearing Person - August 12, 2024