Exploring structured content for your documentation

Structured content is a tricky concept to understand, but it’s primarily a way of managing information.

The “structured” part of the term does not refer to the content itself, but rather information stored about that content. For this reason, you can say that structured content is interface or platform agnostic.

Normally, content is handled as inseparable from the page or channel on which it is being displayed or published. When you write and publish on your WordPress site, you end up with a website page linked to the file in the CMS (Content Management System). If that file is deleted, your web page disappears too.

If the original content is stored anywhere centrally, this might be in Google Docs or Microsoft Word files by the writers and editors. Content in this traditional methodology is normally treated as disposable. If you need the same content again, you either copy and paste it, or write a fresh version.

In structured content, content is treated as data to be stored, managed, and reused. It’s separated from its final mode of presentation – similar to the way that HTML on a website is separate from its CSS styling. Structured content for documentation is managed by technical authors using specialized software tools, and can be governed by information standards.

What is structured content

So what exactly is structured content? According to the experts:

“Structured content is a modular approach to managing digital content that uses metadata tags and automation to publish content from a single source to multiple distribution channels. Structured content allows content creators to enter text once and use rules-based publishing to tailor the output for a specific delivery platform.” (Tech Target)

Structured content is often used in the enterprise because it works best for large amounts of content that you need to re-use. It generally assumes you will have teams of people working on your content, and that you will need to regularly edit your content and distribute it over many platforms (for example, print, mobile and desktop).

Of course, structured content can be structured in any way that you want it to be, and you can define the tags that will be useful for your own methods of publishing. These tags could include elements like: paragraphs, tables, lists – anything that comprises the final format of your documentation.

There are also standards for documentation available that help you structure your content – like DITA or DocBook. Along with these official standards, structured content is usually produced using a multi-step toolchain. For example:

DITA standard >> oXygen XML Authoring tool >> Gatsby Static Site Generator >> final documentation site

This example workflow would result in a static site for your documentation, with the documentation content being pulled from the database in your Oxygen platform. Of course, in reality, things are usually much more complex.

What structured content is used for

Structured content is: “Content, whether in a textual, visual, or playable format, that conforms to structural and semantic rules that allow machine processing to meet specific business requirements.” The Language of Content Strategy

It can be used for both marketing and documentation, since both of these fields are responsible for creating large amounts of content. Structured content doesn’t actually tell you how to style your content (that would be the job of something like HTML for the web), but contains information about what your content is to be used for. For example, you could label your content as being a ‘definition’, a ‘code block’, or ‘disclaimer’.

An example of a common way to structure your content is using XML (eXtensible Markup Language) which is what DITA is based on. The content is stored in a format where it has been marked up with tags that tell you something about the nature and purpose of the content.

Structuring a note is a good example:

Image source

This XML markup content will be fed into a software client, and then result in content that is represented something like this:

Image source

XML means tagging your content with metadata that gives you more information about the content and its nature.

Example of structured content

DITA (Darwin Information Type Architecture) is an XML architecture for designing, writing, managing, and publishing information. While XML has no predefined tags, DITA defines your tags for you and has been especially developed for outputting to multiple formats – EPUB, CHM, PDF, Web Help, and so on.

DITA is a standard for structured content used by many technical authors to write their documentation. It must be used in conjunction with an editing tool like oXygen.

Using Ditamap files, you can create your content topics once and then create separate projects reusing the topics. You could create a printed manual and the HTML files for a knowledge base from a single source. Here’s an example of a Ditamap file:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="map" xml:lang="en">
  <topicref format="dita" href="sample.dita" navtitle="Sample" type="topic"/>
</map>

Source: Wikipedia

Madcap Flare is a popular Help Authoring Tool that supports structured content creation and publishing, and an alternative to DITA-based publishing systems.

Benefits of structured content

Single-sourcing your content is far and away the most significant benefit of structuring your content. Structured content reflects the diversity of platforms that modern businesses need to publish across – PDF, desktop help, print manuals, desktop and mobile web, as well as native apps. It’s no good creating the same content over and over for all these different platforms. It’s better to centralize the content in a database and have it managed by a content team.

You can tag your content, so if you need to make an update it also means that you can update that content tag in all the places that it appears. This is an advantage that results in increased productivity.

Structuring your content opens it up to the possibility of machine automation, so your content strategy becomes that much more powerful. You can potentially reduce translation costs by translating your single source of content and reusing it on multiple outputs.

For many organizations, standardized documentation is a legal requirement, so structured content is an important way forward for efficiency-focused and compliance-focused teams.

When to avoid structured content

Structuring your content is not always necessary if you only want to create a dedicated knowledge base for your product or service. SaaS applications like our very own KnowledgeOwl are perfectly suited to this purpose.

KnowledgeOwl treats some of your content in a structured manner using the snippets function. You can define content you want to reuse as a snippet, which is stored in the snippets library, and then insert your snippet on the necessary pages. Updating a snippet once in the library updates all instances in your knowledge base.

Also, you can manage your articles and categories using the overview features that allow you to bulk update multiple pieces of content. With KnowledgeOwl, you also have an end-to-end publishing process which includes content creation, content management, and front-end content publishing. One price, one tool.

Some might argue that you should avoid structured content altogether, because content cannot be separated from its form. In order to maintain a coherent flow and user experience, content must be adapted in each and every instance.

Final remarks

It’s better to think of structured content as a way of working with information in a technical writing capacity, rather than a concrete object. In fact, structuring content exists on a spectrum, and you can use semi-structured content for a more efficient documentation workflow.

If you want to take a semi-structured approach to your content, consider our knowledge base software KnowledgeOwl. You won’t be tagging all of your content as you would in other structured content software, but the system allows you to reuse and define your key pieces of content, as well as bulk update your articles and categories.

Take it for a free spin.