A Source of Potential Component Conflict when Multiple Authors Work in Structured Authoring Environment

Multiple authors writing “components” instead of “pages” is the future of technical communications (if not technical training and e-learning).

When it comes to documentation, it really makes sense to “write once and publish multiple times”, as the saying goes. And that’s only possible if we all get used to writing “components” (sometimes also referred to “topics”), which can be as small as a single word, a sentence, an image, or perhaps an HTML link. That’s the core design idea in all structured authoring and single-sourcing platforms.

Structured authoring is not possible without a DATABASE sitting in the center of the whole “authoring architecture.” Documents, components, images, library snippets, etc. must all be kept in a relational database like SQL to keep track of all the changes and make sure the latest copies of components are used to assemble the end product (which can be anything from a traditional book to an iPad screen).

When you are the only author working in such an environment there is no problem. You check out your document from the database; you work on it however you please; and then you check it back in. Your work is done.

Problem

But when there are multiple authors in the same office (or structured authoring system) working on DIFFERENT documents, that’s when things can get interesting in a hurry since all authors would be accessing the same database and using the same set of components.

I’m trying to understand how to prevent the following potential problem (see the diagram below):

Author A checks out her own document Doc A from the database, edits Component X, and saves everything back into the DB. By its very design, the system will not allow Author B to change the same component while Author A is working on it — which is great and how it should be.

But what happens once Author A checks Component X back into the database as Component X2?

If the same component has earlier been used in Doc B by Author B, wouldn’t that change the way Doc B reads since the same Component X is now Component X2 there as well?

I have a feeling this is one potential “problem area” in structured authoring that needs to be addressed.

Solutions

Here are some potential solutions that unfortunately come with their own issues:

(1) Keep the components as bland, generic, and granular as possible and add unique (non-component) text as necessary for one-time use only.

This solution makes sense accept it goes against the grain of the whole “write once, publish multiple times” philosophy. No doubt, fresh text is necessary since we cannot assemble our documents from A-to-Z by using modular components alone.

But where is the balance between ready-made components and embedded unique content? This is something that each tech pub team needs to sit down and agree among themselves.

(2) Create user-defined variables for each specific document.

Sounds good in theory but when you’re writing a 100, 500, or 1,000 “page” document, the number of variables can easily multiply like rabbits, making it hard to select and manage them. Even naming them can present unexpected problems if you end up with hundreds of variables.

And the same problem may crop up again if you edit the “definition” of the variables to fit your particular document needs. When those variables are shared through a common database, you again would have the same problem of changing another author’s content without her consent or information.

(3) I heard “conditional text” (which called a “variant” by some applications) offered as a solution. This may work if the whole conditional text block itself is one single component. That way you’ll either use it for the purpose it was intended for, or not.

But if there are individual components embedded inside the conditional text block, you’d be back at square one, asking the same question all over again: when a component is edited by Author A, that would change the Conditional Text Block A also according to the Author A’s wishes. If Author B uses the same conditional text, again she might be in for an unexpected surprise.

Conclusion

I do not believe there is any automatic “machine solution” to this potential multiple authors problem.
All technical writing teams need to get together and discuss the ARCHITECTURE of their project before starting to write it. They, for example, need to decide how “granular” their individual components need to be. They need to decide what kind of variables and conditional text they need to use.

Document projects launched without such a common understanding on the building blocks of a structured authoring edifice would face the possibility of losing its consistency and reliability in mid-stream.

Technology is a great thing. But as this discussion hopefully demonstrated, it’s never a substitute for intelligent planning and establishing the rules of the game before typing even a single word on the screen.