Tag, you’re it! Playing nice with DITA

When we create content, whether it’s a blog post or an instructional guide, we think about our own requirements. What does the style guide say about how to word this phrase? What formatting do I apply here? But if we pull back and look at the other teams that we work with, there’s a broad spectrum of content needs which often don’t line up.

However, there are still opportunities to bridge between silos, and ways to allow different teams to play together.

One of the main differences with content between different groups is the focus of that content. Who is the audience? What are you trying to communicate? Depending on the answers to those questions, it’s not unusual to wind up leaning towards one side or the other of the Design Divide.

At one extreme, we have a focus on making sure that the content is available and correct. Internal developer resources are (hopefully) comprehensive, but aren’t known for being pleasing to look at.

At the other extreme, the focus is on how content is laid out, serving to highlight specific information. A marketing one-sheet might point out a prominent product feature, but further details might be in a whitepaper.

There are some pretty significant differences in how these groups create their content, and that’s fine! Nobody is creating ads that include dense paragraphs on the benefits of the product, and you won’t find internal wikis with fine attention to hyphenation when wrapping to a new line. But even with these differences, there’s still an opportunity to find ways to share and align content between groups.

Bridging the gap

While different groups aren’t going to align on presentation, there’s still common information that they’ll all need to stay aligned on:

• Product names
• Product features
• Media

Using DITA allows for content to be semantically identified, while remaining formatting-neutral. A developer’s database might map to a specification table in technical content, which gets repurposed for a blog post. The key is finding out what information groups align on, and then planning for how to act on that.

1) Itemize
What do we have to work with?

Collect the different kinds of content that your groups use. Focus on representative pieces of information, like a common topic format, or high-value content.

2) Categorize
How do these pieces fit together?

Now that you have your content, look for pieces that overlap. Does this marketing brochure use a table that’s defined in a user guide? Does this technical guide refer to a developer’s error codes for troubleshooting? There may be content that doesn’t share well, but that’s fine!

3) Strategize
How do we use this stuff?

While something like a product image or icons might be straightforward to reuse between groups, it’s more difficult to use informational content; a developer’s JSON file is a useful reference for a technical writer, not a source for publishing.

Strategies for sharing

Ownership

If groups are sharing content, it’s important to identify who is the sole source of that content. The marketing team might claim the product images, and the technical writers might manage all of the specification tables, but there always has to be a Single Source of Truth.

Reuse

If different groups are already in DITA, they may be able to share their content directly. However, one group’s topic might have insufficient (or too much!) detail for another group’s needs. Groups may also be able to use more granular reuse methods, like conrefs, to pull particular information into their content; you might not need that full data sheet, but that specification table is useful.

Repurpose

You might also want to consider transforming your content. Say your developers store error codes in a JSON file, and your technical writers create troubleshooting topics on how to resolve that error. If your content is semantically rich, you can create a DITA transformation that turns those troubleshooting topics into an error code JSON file. This saves developer effort, but also ensures that your documentation and software are always in alignment.

It’s also possible to transform segments of DITA content for headless delivery that can be repurposed as necessary.

Take a look at what you’ve made, and what other teams have made. Have you had pain points around content getting out of alignment? Do you know someone who bought a new drill bit set because the playhouse documentation was never updated to call for the 3/8″ bit they already had?

Questions for Jake? Contact us!