Nailing Analogies

nailing analogies

Nailing Analogies

Posted on August 2018

Frank to Doug..... Wake Up!

Frank: Doug, I see that you haven’t moved at your “work station” in the in the last hour or so. Have you adopted my successful work habits? Are you waiting for a cookie, like I do before starting work?
Doug: No, Frank.
Frank: You haven’t hit a key or even surfed the Web for at least an hour. I’ve been watching you with one eye open. What are you doing?
Doug: I’ve been trying to think of a fitting analogy for structured writing and structured mark-up both in technical pubs departments and across large organizations.
Frank: What’s an analogy?
Doug: It’s a simple way of developing a basic understanding of something that is complex.
Frank: You mean like “working” to me looks a lot like “sleeping” to others.
Doug: Yes, Frank.

If all you have is a hammer, everything looks like a nail.

Here a Topic. There a Topic. Everywhere a Topic, Topic—Whack, Whack, Whack. From one side, when implementing DITA, some technologists seem focused primarily or even exclusively on reuse. Often, to them, everything looks like a DITA Topic. Simply XML has seen a lot of DITA Topics that are one sentence or one paragraph long but also some DITA Topics that are 50 pages long. The thinking in favor seems to be that Topics can be reused so, if it might be reused, it is a Topic—no matter what the length.

When technical writers have all the tools in the world, they can, and might, use as many as possible.

Out of the box the DITA tag set has more than 600 elements. It is true that no one uses them all. But some technologists use a large number and then expect their enterprise authors to use the same granular tag set. This is expensive in time, training, and money. And it is unrealistic.

Simply XML had a customer in the Chip Industry that said their enterprise authors could not use Content Mapper unless it supported some of the UI, Software, and Programming Specializations. We took the time to program them into Content Mapper with .NET. Guess what? Their enterprise authors don’t use them! If you are building a tree house, you need some tools. If you are changing a carburetor, you need other tools. If you are building a bookcase, you don’t need a huge amount of expensive tools. And if you are authoring enterprise content you need to Keep It Simple, Smart-person.

Bottom line for technical publications staff:

Technical writers may have a granular technical understanding of DITA. If they are trying to source content from outside of their department, they may be missing a clear understanding of the content that enterprise authors develop as well as the structured authoring piece. There is more to enterprise content management than just modularizing content so it can be reused. They may be missing other structured authoring principles like audience orientation, relevance, consistency, organizational hierarchy, and even information typing beyond task, concept, and reference. Information consumers can get chunks of information, but sometimes lack the context they need to be effective. Beyond structured mark-up with DITA, technical writers often need a broader understanding of topic-based writing. Technical writers need to understand what structures and tools are really needed and how to apply them. Content needs to be organized in a hierarchy with multiple levels and there are often 4-6 layers in the hierarchy. From an information architecture perspective, technical writers using DITA need to determine what a Topic is. Topics can have sections and multiple levels of paragraphs. Topics can also be assembled into DITA Maps and DITA Maps can be assembled into larger DITA Maps. Nailing the hierarchical structure may be the most important decision an organization needs to make regarding their DITA architecture.

When enterprise authors know structured authoring, they can create content that works.

On the other side of the equation, there are enterprise authors, sometimes SME’s, who have a vast amount of knowledge. They understand the need to focus content on the information consumer. They know how to organize that content in a consistent way and how to present it in a hierarchical structure. They are not technologists but they sometimes use technology tools in their work. They primarily work in MS Word and use PDF as their output. Information consumers sometimes receive too much information but not in HTML, Mobile, or CHM formats. Enterprise authors need a way to structure content to release themselves from the constraints of large documents only in PDF.

Bottom line for enterprise authors:

Enterprise authors are often stuck in the world of large documents published to PDF. They have created a vast amount of effective content that can be printed in a beautiful PDF, often with the Microsoft Publisher or high-end publishing tools like Adobe InDesign or Antenna House. Their first approach to web and mobile output is to make the PDF available from those devices. Beyond topic-based writing, enterprise authors need a technical mark-up system to modularize and tag content for reuse so they can publish just enough of the right content from a single source to HTML, Mobile, CHM, and, yes, PDF. Enterprise authors need an authoring system that lets them work in MS Word, but that has an XML architecture underneath. This will improve modularity, reuse, and publishing to multiple devices.

Bottom line for the enterprise:

In financial terms,


Frank: I think you nailed it, Doug. What’s next?
Doug: Well Frank, I’m glad to say that working with one of our CMS Partners, we just landed a sale for 4000 licenses in Europe. Get ready to help them use their hammers, other tools, and structured authoring appropriately.
Frank: Let’s each have a cookie.
Doug: OK, Frank. Thanks for your help.