Things to Avoid in Modular Component Writing for Structured Authoring and Single-Sourcing

In true “structured authoring” the “components” you create (write, draw, etc.) are saved in the database of a Content Management System (CMS).

The negative side of this type of “writing” is that you lose the local context and formatting. What you’re creating is not “only” an X-type of document but a “component” (let’s say, a line of command to close a window) that may not make much sense on its own.

The positive side of the same is the power it gives you to recombine, to re-purpose and use the same component over and over again with other components to create new modular content published on many different platforms. You really “write once and publish multiple times.”

The result is a tremendous gain in productivity, time and money.

However, you need to adopt a new set of writing habits when writing components instead of whole “guides”, “manuals”, “presentations”, etc.
For example, you need to refrain from “legacy expressions” such as “as we’ll show you down below”, or “as the above figure suggests”. Why? Because you never know how your component will be published and what will be “down below” or “above” it in the new context.

Also forget about the whole “header” and “footer” idea which is a legacy of the whole book/codex metaphor. If your component gets published in a traditional book format, yes, you will have a header and a footer. But if it’s pushed into a help file or a kiosk display format, then there won’t be any headers and footers anymore. Therefore try not to write things like “see footer 12″ or “here is how you can change your header information”“.

The whole “page” concept goes down the drain too, together with things like a “page number” because your next “document” may not have a page number at all, as all user assistance (UA) authors know. So think twice before writing something like “we’ll explain this in full detail in the next page.”

In short, all positional navigation references like “as seen on the right side” or “please refer to the left of this column” will not work in a CMS because what is “right” on your screen may very well end up being “left” when your component is single-sourced to another document, on another platform (a cell phone, for example).

So, welcome to the brave new world of single-sourcing, component writing, and CMS publishing.

Remember that old American Express commercial in which Karl Malden used to stare at the camera, holding an American Express card, and say: “Don’t leave home WITHOUT it!” ?

Let’s paraphrase: “STRUCTURED WRITING — Leave home WITHOUT some of your most cherished writing conventions and produce more!”