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:
| USE | FORMATTING REQUIREMENT |
| Contract | Numbered. Left aligned. Time New Roman, 12 pt. |
| Software Licensing Agreement | Block justified. Arial. 10 pt. |
| Online End User Agreement |
Left aligned. Arial. Font size dependent on device screen size.
|
| Warranty Section in User Manual | Numbered. Left justified. Calibri. 11 pt. Italicized |
| Rock Climbing Waiver | Times New Roman, 10 pt. Bold. Two-columns. |
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
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.
- 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
- How to Improve AI Performance? Do This One Thing to Your Content - May 20, 2024
