Anyone who knows the answer to the question, “what is technical writing?” or that has been in the technical writing world for some time has probably heard the phrase “structured authoring,” or “structured content authoring.” But what is structured authoring?
First, the concepts of structured authoring are not new. The fundamental ideas behind structured authoring were first introduced as early as the late 1960s/early 1970s. However, it was not until the 1990s and the advent of markup languages that the implementation of those early ideas started to become more common.
In the early days of technical documentation, it was very common for a technical writing team to develop a style guide. A style guide was a documented approach on how that team would author content, everything from how many heading levels deep an article would go, to the handling of images in a document, even to grammatical choices such as to use/not use the Oxford comma. The adherence to the style guide was supposed to be self-policing on the part of the technical writer and was often then double-checked by editors. This manual process of ensuring style guide adherence was very time-consuming.
Addressing the Early Issues and Questions Around Structured Authoring
Some of the core ideas of structured authoring were techniques to define the authoring requirements, not as a style guide for humans to enforce, but rather, as a set of logic statements that could be enforced by a machine.
In this way, if an author broke any of the rules, their content was then flagged as invalid or going against the defined publishing rules that the company wanted to follow. A structured authoring system could, in this sense, be completely automated. This quickly led to many questions on the topic, including:
Do We Still Need Professional Writers with Structured Authoring?
The answer is absolutely! The question on its own is a scary thought. Unfortunately, in the beginnings of structured authoring, there were some that believed that it could be used as a cost-cutting measure. With a strict set of content validation rules in place then lower-cost staff could take over the content authoring duties. After all, it is now structured, right?
It was quickly discovered that this was the equivalent of “paint-by-numbers” in the art world. Sure, the final painting might have some resemblance to a famous piece of art, but it will not fool anyone.
Do We Still Need Editors with Structured Authoring?
Once again, this was seen as a cost-cutting measure, but editors do much more than look for style guide variances. Simple things like typographical errors or grammatical errors are not typically caught by structured authoring rules. Editors can also verify that the core important concepts are truly being communicated, also beyond the capability of a structured authoring validator.
Is Structured Authoring Better than Unstructured Authoring?
Absolutely not! The problem is in implementation. A completely unstructured, or stylized process might be too far in one direction, and a completely locked down structured authoring methodology such as DITA may go too far in the other direction.
Extremes, in any discussion, are not always the correct answer. While completely unstructured authoring may lead to a disaster in your content publishing, conversely, a tightly locked down fully structured authoring solution may be far too rigid for you to meet your content publishing goals. It may help to look at two fictional, but representative scenarios of structured content authoring.
An Unstructured Authoring Scenario:
A company wants to standardize its operating procedures. They bring in three dedicated writers for the task. They provide little guidance to the writers, simply instructing them to, “write up various procedures that are directed by their technicians.”
As you may have guessed, this project does not go well. They end up with dozens of written procedures but there is no consistency. The procedures written by author A look completely different than the procedures written by author B. Some procedures are just a list of steps. Others include prerequisites and safety information. Some procedures include digital photos and others do not.
The manager in charge is not happy. The manager does a little research and decides, “What we need is structured authoring!”
A Structured Authoring Scenario:
The same company wants to standardize its operating procedures. They bring in three dedicated writers for the task. This time, at great expense, they have brought in consultants that have programmed a custom structured authoring solution for them. This will force consistency between each writer. They now have high hopes of success and they start the process.
Everything seems to be going well. In the first few review cycles, all the procedures are looking very consistent and very professional. The manager is happy. Then the first challenge.
One of the stakeholders, the company safety officer, has some criticism, “This procedure here can be quite dangerous. After the introductory paragraph, but before the list of steps, we need a digital photograph showing the equipment with the appropriate safety guards in place.” The writers respond that they cannot do that. The validation rules provided by the consultants only allow images in the procedure steps. Adding a photograph anywhere else would produce an invalid document.
The writers have no control over this, but the safety officer now complains to the executive staff that “the documentation team is far too rigid in its content rules and consequently trying to publish dangerous procedures.” This creates drama — unbudgeted money must be found to bring the consultants back and have them reprogram the validation rules. The project is now behind schedule and over budget, but the manager is happy, and the safety officer is happy with the content. Then the second challenge.
The marketing manager drops by and is not happy. They have seen a copy of our new procedure manual and it does not meet the requirements of “the corporate look and feel.” The marketing manager wants some colored geometric shapes added to the pages for interest and to match the current branding of other published material. One of the writers responds to the marketing manager, “You are in luck! The validation code was altered so we can now place images anywhere. However, what text caption do you want us to add to these colored shapes?” The marketing manager is confused, there should not be any text, these shapes are purely for visual interest. Time to find more budget and bring the consultants back. The current validation rules make the inclusion of a text caption mandatory on all images in the structured document.
Now the project is even further over budget and further behind schedule. There must be a better way.
MadCap Flare: The Perfect Marriage of Unstructured & Structured Authoring
Those two scenarios above are why we developed MadCap Flare: to provide a sliding scale of structured authoring capabilities that you control instead of the 100% off/100% on binary choice that is traditional. But no matter the authoring tool that’s used, structured authoring can still be difficult for beginners. That's why Flare can be used in a completely unstructured manner if the customer prefers.
However, as the skills of the author or the team grow, they can do more and more to lock down their content creation process to add structured guidance and content rules for their authors. Such a migration might look like this as your needs and guidelines progress:
Day 1 – Use Flare in unstructured content mode
As soon as comfortable – Implement topic templates with style/metadata pre-applied
To “discourage” inline formatting – Disable inline formatting tools (bold button, italic button, etc.)
If necessary – Establish a MicroFormat using class names for custom metadata
If desired – Establish complex-selectors in the style sheet so that styles apply themselves based on page structure
– and so on…
All of the above items could be implemented on day 1 or phased in slowly as you desire. What is important is that you have the control over the structured authoring environment to fit both your content rules and the needs and workflow of your technical communicators.
The list above is not meant to be a road map, or a recipe to follow, but simply an example as to how MadCap Flare can be configured over time to be less unstructured and more structured, without the need for custom programming or consultants. In sum, the more structured your Flare project, the easier it will be to keep consistent organization of your look and feel across a large team or a large project. However, you can ease into the level of structure that you are comfortable with and not have to jump directly into the “deep end of the pool” with all of the additional expense and complete rigidity of highly structured authoring.
