I have one more thread to add to our structured closet and little black dress analogy: terminology.

There is a close-knit relationship between terminology and structure. So close, in fact, that many people completely overlook it. I’ve tried to explain this many times and, for some reason, I don’t think I have been able to make the point as clearly as it needs to be. So, in this post, I will try to tailor it for everyone.

Let’s imagine that you have taken your big, messy closest and built in one of those really nice closet organizers. You have some structure – empty of course – but structure for your clothes and accessories. That’s a great first step!

As you go shopping, you buy shirts, sweaters, jackets, socks, power undies, and so on. You start filling your structured closet with content and, because you took the time to set up structure, every item has a place. Items can be groups by type, season, color, really the categorizing of the contents is up to you. The main thing is that you have a system of organization. It important that the system makes sense, so that everyone who puts things into your closet (your housekeeper) and takes things out of your closet (your best friend) knows the structure and can follow it.

Next, we discussed reusing content. Reusable content is like having that one piece of clothing that is just perfect in all situations. The famous little black dress that can be worn over, and over, and over again in many different situations, and it always fits right in.

Your content management system is like your closet. Structured authoring methodologies, such as DITA, DocBook and so on, are like the shelves and drawers that you use to organize various pieces of content. Taxonomy is the system for organizing the chunks. Metadata and tags are the indicators for how to locate each type of content, to make your red shirts searchable, if you will. So far so good? If not, please go back and read these previous posts here and here, and then reread this section.

One of the reasons for structuring content is to increase the possibility of reuse. It’s certainly not the only reason and some folks would argue that reuse isn’t the most important reason. But, it is a reason why many companies move to structured authoring. For reuse to be possible, the content needs to be written in such a way that a chunk can be used in multiple locations.

Perhaps you will reuse content among a printed document, a web-based document, and an eBook. Or maybe you are writing installation instructions that can be shared among documentation, training, and the corporate knowledge base. Or perhaps you are describing how to install a particular piece of hardware and many different pieces of hardware could use the same basic instructions if you word it right. (Pick up the chassis, put it in the rack, tighten the screws, plug it in, power it on, watch the lights flash, done. Lather, rinse, repeat for the next type of chassis.)

An information asset, or final deliverable, contains a bunch of reusable content chunks.

This methodology works great in theory. It makes perfect sense; almost everyone can understand it. In practice, it is not so simple to achieve.

One of the biggest breakdowns I see when customers try to “build” an information asset from various chunks is the mismatch of the words each chunk contains. Sure, you can take all those pieces and create something from them. But, if there is no standard for the terms that are used in each chunk, you end up with a nicely built document that is very confusing.

Let’s try the analogy. You are getting married and have asked 7 different people to be your bridesmaids. You have told them each to wear a black dress. You are looking forward to taking wedding photos and expect all of the bridesmaids to show up in the exact same dress.  Lo and behold, your wedding day comes. Rather than have seven identical dresses, you end up with seven black dresses, but each one is unique. Your photos are a disaster because you wanted your wedding party to be uniform. You burst into tears.

You cannot expect seven different people to purchase the exact same dress if all you told them was to go get something black. In fact, you can pretty much guarantee that if all you said was the color, there is very little chance that the dresses will match.

Same with putting together content asset from disparate chunks. If you do not have very precise and enforced terminology, you will end up in tears. Or at least your reader will end up in tears, or worse, calling technical support for help.

Sometimes it boggles my mind when customers go through the incredible effort and expense of implementing a great CMS and creating strict content models, without paying any attention to terminology. If I call the box a chassis, and you call it a router, and someone else calls it a switch, and a fourth person calls it a device, and a fifth person calls it a box…and then we try to take the “reusable” writing from all of those people to create instructions, we end up with a big, well-organized, incomprehensible mess.

To make your chunks reusable among different final products, mixed with chunks from other content creators, you must decide on terminology in advance, and then enforce it in practice.

Otherwise, you could end up running from the altar.


Val Swisher
Latest posts by Val Swisher (see all)