Structured Writing Part 1: What is Structured Writing?
Structured writing is an approach to creating content that fits into a larger content strategy. It has many different components and can be applied in many different ways, offering numerous benefits and challenges as well. Since this is a wide-ranging topic, I’m going to share my thoughts on structured writing in a series of blog posts, starting with a high-level approach to structured writing and ending with concepts of authoring in XML using the DITA standard.
Structured writing is an approach to writing that focuses on the structure of content and it includes evaluating and defining types of content, applying and creating rules around the structure, validating the rules and defining styles to apply to the content so you can publish it. You can apply structured writing to all types of content from writing a simple letter in Microsoft Word to a 400-page technical instruction manual in Adobe FrameMaker to a product online help system in MadCap Flare. You can also impose all kinds of rules from the number of heading levels to the number of options in a list. The possibilities are endless.
In this series of blog posts, I’ll focus on structured writing in terms of technical content authored in XML using a structured writing program and following the DITA standard. I’ll provide a high-level explanation here with details to follow in subsequent blog posts.
Evaluating and Defining Types of Content
Structured writing begins with taking a very detailed look at the types of content you produce so you can define and put structure around them. For example, if you create Quick Start Guides (QSGs), you have some instructions and probably things like customer service phone numbers. If you look across the QSG set, most likely you’ll find that the information is very similar and could be standardized, at least to a certain extent. I’d recommend that you conduct a content audit first. Then you can start to define the types of content you have and think about the general structure. Ultimately you want to create reusable, topic-based chunks of content and apply structure to it. Here’s a simple set of instructions on how to verify package contents, which is used in several QSGs:
How to Verify Package Contents
- Open the box.
- Find the packing slip.
- Compare the contents to the packing slip.
Applying and Creating Rules around the Structure
Once you’ve culled your content, you need to establish some rules around it. Structure-based authoring programs come with rules or you can create your own. As I mentioned previously, you can create all kinds of rules. For example, every QSG needs to have an introduction, two sets of tasks and a customer service topic. You can also create much more granular rules like every list needs to have three items.
Here are some rules for the previous example:
- Introduce the topic with a heading.
- Number the instructions.
Validating the Rules
Once you define the rules, you have to validate them. In a structured writing program, it’s easy to tell if what you’ve written isn’t valid because the program will give you an error. For example, this would give me an error:
(no heading)
- Open the box.
- Find the packing slip.
- Compare the contents to the packing slip.
Defining Styles to Apply to the Content for Publishing
In order to publish your content, you’ll need a style sheet to define the styles because formatting is separate from content. You could use the one that comes with the program but you’ll probably want to adjust it to use your company’s styles such as fonts, colors and spacing. In our example, I could change the style sheet to have the output look like this:
How to Verify Package Contents
- Open the box.
- Find the packing slip.
- Compare the contents to the packing slip.
Conclusion
Structured writing contains many different components, which I’ve explained here at a high level. In future blog posts, I’ll start drilling down into these components. In the next blog post, I’ll talk about where you might want to apply structured writing and some benefits.
