Structured content does not kill creativity

Structured content is cooler than you may think. As a model for technical communications, it suffers from several misconceptions which prevent that you and your organization get the most out of it.

I’ll debunk a couple of misconceptions that I’ve encountered. Each one presents a learning opportunity where you can show a writer, a subject-matter expert or a manager how structured content is actually quite beneficial.

Myth #2 is:

Structured content kills creativity, right?

The argument is that the structured content forces you into a corset of rules and reduces you to filling in the blanks. It means to comply with a structural model which can get quite intricate. For a procedural topic, rules could include:

  • Start the topic with a heading; start the heading with a verb.
  • Start the text with an introductory phrase, sentence or paragraph, depending on how much context the procedure requires.
  • Write all procedural steps in a numbered list.
  • Etc.

Channeling creativity

I think the argument, taken at face value, misunderstands creativity. Creativity, whether in the arts or in more craft-like professions, is always an expression regulated by rules and confined by boundaries.

Think about poems. Ann Rockley (I think) once gave the example of a sonnet, a fine form of poetry which has been around with few changes for centuries. It is highly regulated in terms of number of lines, rhyme scheme, etc. Or think of a haiku: 3 lines of 5 + 7 + 5 syllables, that’s pretty strict. But I’ve never heard a poet claim that the rules kill his or her creativity.

So structured writing sets up more obvious rules than you may be used to. With them, it channels creativity to ensure that your writing is more reliable, more accountable and to your readers more useful.

Anybody can write?

Filling in the blanks in a structured writing template seems more mundane and banal than to write one paragraph flowing into the next. This can lead to the idea that structured writing might somehow be easy…

Structured writing is mainly different from technical prose, I think – and ultimately just as demanding. In both scenarios, you can ask yourself: Have I put my best sentences into the topic? And in both scenarios you will meet people who think that anybody can write. But the marks of high quality writing are pretty similar in either case: Is the writing clear, consistent, and correct?

Your benefits

For you as a writer, structured writing doesn’t so much limit or kill creativity, but it helps you to channel it: You can focus on putting the most useful, most concise documentation on screen or page in consistent structure. It frees you from having to worry about structure, content and layout at the same time: You can focus on content alone, while the structure is given, and the layout is applied separately.

For readers, structured writing increases their trust and confidence in the documentation. Whether you spell it out explicitly or leave them to discover it by themselves, structured writing ensures a level of consistency that is hard to achieve by other means.

If you’ve found this post helpful, if you disagree or if you know additional benefits of structured content, please leave a comment.

Structured content is not just a style guide

Structured content is cooler than you may think. As a model for technical communications, it suffers from several misconceptions which prevent that you and your organization get the most out of it.

I’ll debunk some misconceptions that I’ve encountered. They aren’t exactly wrong, but they miss the big picture. So each one presents a learning opportunity where you can show a writer, a subject-matter expert or a manager how structured content is actually quite beneficial.

Myth #1 is:

Structured content means writing topics with a style guide, right?

No, but it’s a good start! Structured content plays very well with topic-based authoring and a style guide, but it goes beyond them. Way beyond.

To take a favorite example, imagine you’re writing a cookbook with several co-authors. Without topics and a style guide, every writer’s output looks different, though they’re probably all effective and recognizable as recipes.

A topic structure gives you some coherence in all recipes. They each might start with a short description with regional and culinary context. Then you have a list of ingredients. Then you have the preparation instructions, probably as a list of steps. You may include preparation time and difficulty.

A style guide adds more coherence, this time in layout and maybe sentence structure. You define what headings and sub-headings you use. You decide on metric or imperial measurements. You might regulate that instructions should use imperatives.

Surface structure

On the surface, you now have structured content: All recipes share the same structure and layout and similar writing style. You can mix and match topics. If you have 200 recipes like this, you could easily combine them into a dozen different cookbooks, some with a regional theme, one with desserts only, and a vegetarian one.

A problem arises when you show ingredients in grams and liters and want to convert them into ounces and pints. You could do that manually for 200 recipes. Or you could ask a developer to write a text manipulator that searches for “grams” and “g” and “kilogram” and “kg”, finds the number preceding it, convert it and hope that you catch everything, and it comes out right.

“Smart” structured content

Structured content helps with such conversion, because each topic “knows itself” inside out: Each topic contains markers that identifies it as a recipe. Inside these markers are more markers that set off the intro, the list of ingredients and the step-by-step instructions. Each ingredient on the list identifies an amount, a unit and the actual ingredient.

The benefit of such structured content is that it can be parsed automatically, reliably and efficiently to make it more useful:

  • You can convert measurements.
  • You can compile cookbooks automatically, if each recipe “knows”
    • its country, for example, France
    • its region, for example, Mediterranean
    • its type, for example, dessert
    • its preparation time, for example, 20 minutes
  • You can offer the same recipes online and allow users to search for
    • Mediterranean cuisine (because that’s what they feel like)
    • which is easy to prepare and takes up to 30 minutes and
    • uses aubergines and tomatoes (because they need to go).

Your benefits

Your organization can reap similar benefits, given it has enough content and enough scenarios where you need to reuse it efficiently. For example:

  • Benefits and motivation for a new product or module may already be contained in documentation (or even the development specification), so marketing can just reuse it.
  • Setup procedures in a user manual can be reused in tutorials or training materials.
  • Topics written for online help can be reused in manuals.

If you’ve found this post helpful, if you disagree or if you know additional benefits of structured content, please leave a comment.

And check back next week for myth #2: “Structured content limits kills creativity, right?”

Top 4 tactics to structure legacy documentation

The success of a move to topic-based authoring and/or structured writing depends on the order of your steps – and good planning is key. You can’t make it up as you go along.

The Company I Work For is moving its extensive user documentation to topic-based authoring and a DITA-compliant information model. That requires converting existing documentation, such as user manuals.

Many current manuals are like tutorials: They guide readers by example with lots of screenshots. They are easy to follow along, but more difficult when you need to know about individual procedures or about scenarios which don’t match the example.

I’m currently converting and restructuring some of these user manuals into topics. Basically, I’m taking them apart and reconstructing them into concept topics, procedure topics and reference information.

Here are some lessons we learned in the process:

1. Define the structure first.

Even if it takes a week or two, be sure you have 80, 90% of your structure in place before you start tearing up contents to convert them. If you simply make it up as you go along, you’ll get an abstraction of whatever content you start with – which most likely won’t suit all of your contents.

You’ll be better off, if you at least sketch out the common topic types such as concepts, procedures and reference and define what goes into them in which order.

For example, procedure topics could contain

  1. One or two intro/context paragraphs
  2. Prerequisites (if any)
  3. Procedure as a list of numbered steps
  4. Expected results
  5. Exception handling (if possible and applicable)

2. Carefully select pilot projects.

Start by converting content that is both typical and mainstream. This way, you can validate your structure and discover gaps or errors.

This also makes it easier to show progress and reap some quick wins. You can give managers and colleagues something tangible what the future documentation will look like to ensure confidence and support on your path.

3. Draft the new topic structure.

Use the defined structure to draft a specific structure for the content you’re about to convert. Just leafing through the pages of a manual will give you a pretty good idea which topics you will be able to create from it.

Order all those topics into a structure, so you have sort of a table of contents for the new topic-based manual before you begin. This structure need not be set in stone, if you find you need to arrange or add topics, but it should present a sensible picture.

Ensure, for example, that procedural topics are backed up sufficiently by concept topics so we have room to explain the “what” before you explain the “how-to”. Or, if you have both setup procedures and operational procedures, ensure that setup corresponds to operations.

4. Proceed along the old content.

In the actual conversion process of chunking text, moving it into the new structure and rewriting it, follow along the old structure. That will create a temporary mess in your new structure where you may find yourself dumping random paragraphs and sentences under headings.

But this allows you to cross off section by section in the old manual with the confidence that you have moved it over. This is much faster and more reliable than constantly going back to the old manual, worrying if you’ve left anything behind.

Your turn

Do you find these tactics helpful? What experiences have you had when converting legacy content into structured documentation? Feel free to leave a comment.

When topics don’t quite work

If a topic in your documentation gives you trouble, seems homeless or doesn’t quite “work”, it’s probably because it is mixing topic types.

The company I work for has started to roll out topic-based authoring over a year ago. We’ve seen several benefits already: Topics are easier to find and follow for users and more efficient to maintain for writers. But the transition has not been without problems…

The curse of the ornery topic

One of the biggest headaches for us is the “ornery topic”. Here’s how you can tell an ornery topic:

  • It seems homeless. Regardless where you put it, it seems out of place somehow.
  • It doesn’t quite work. It doesn’t really do what the heading says, but somehow does more or less or differently.
  • It seems essential. You really need the information. You can’t just cut it out.

The #1 cause for ornery topics is mixing topic types. What often happens is this:

  1. We need to explain how to do something, so we write a procedure.
  2. Then we need to provide some context about the task, so we include some concept information.
  3. Then we need to tell the customer about all the available settings and options, so we include some reference information.

Voilà, our topic’s become ornery! – If you’re into project management, think of this as the molecular tech comm version of scope creep.

The cure for the ornery topic

We’ve by now found several ways you can bring an ornery topic back in line:

  • Extract concept information, put it into a concept topic and link to it.
  • Omit reference information in the topic, if it is sufficiently explained elsewhere, for example in online help entries.
  • Make the procedure rule the topic structure, so you have intro/context, prerequisites, procedural steps, result.
    • Limit context information to what fits into an introductory paragraph (and link to other concept topics)
    • Limit reference information to what fits into individual steps (and link to other related reference topics)

Your turn

Have you met any ornery topics in your documentation? How have you addressed them? Feel free to leave a comment…