Skip to content

Writing for multiple audiences

Single-source publishing means producing different documentation outputs from the same content. The core mechanism is straightforward: conditions control which content blocks appear, and Create variable sets swap out values like product names and URLs. The challenge is deciding what to conditionalize and what to keep shared.

Variables require the Team Plans and limits or higher; conditions (the Filters you apply to content) require the Business plan.

The mental model

Think of your documentation as layers:

  • Shared content: the base layer that every audience sees. This should be the majority of your content.

  • Conditioned blocks: paragraphs, sections, or list items that only appear for specific audiences. These are additions to the base, not replacements.

  • Variable values: product names, URLs, version numbers, and other values that differ for each output. The surrounding sentence stays the same; only the value changes.

Aim for 80% or more shared content. If a topic is more conditioned content than shared content, it is often cleaner to split it into separate topics and share the common parts through How component reuse works.

Identifying your filter groups

A filter group is an axis along which your content varies. Common groups:

  • Audience: admin versus end user, developer versus non-technical

  • Platform: Windows versus macOS versus Linux

  • Product tier: free versus paid, standard versus enterprise

  • Region: geographic or regulatory differences

Most documentation teams need one or two filter groups. Three is unusual. If you are using more than three, you may be overcomplicating your content model. Consider whether the variation belongs in separate topics instead of conditions.

Minimizing conditioned content

Every condition is a maintenance cost. A paragraph conditioned on "Audience: Admin" must be checked whenever the topic is updated; it is invisible in the default view and easy to forget.

Guidelines:

  • Default to shared content. If a sentence works for all audiences with minor wording changes, rewrite it to be universal instead of creating two conditioned versions.

  • Condition sections, not sentences. A conditioned paragraph is easy to manage. A sentence with three inline conditions is not. If a paragraph needs multiple conditions, split it into separate conditioned blocks.

  • Use variables for values, conditions for blocks. "Contact support at {support_url}" is one Use variable tokens in content, not two conditioned paragraphs with different URLs.

Conditioned content is easy to create but hard to maintain. You must review every conditioned block during every edit pass to ensure it is still accurate for its target audience. The more conditions a topic has, the more testing it requires.

Designing publication targets

Each Publication target settings combines a Create and organize a map, condition profile, and variable set. Plan your targets before writing conditioned content:

  1. List the outputs you need (for example, "Admin Web Docs" and "End User Web Docs").

  2. For each output, define which condition values to include.

  3. For each output, define the variable values (product name, support URL, and so on).

  4. Create the targets in the map editor with these settings.

Then write content with these targets in mind. When you add a conditioned block, you already know which outputs will include it.

The condition profiles for these targets might look like:

{
  "Audience": ["Admin"]
}

Testing before publishing

Use Preview conditioned content in the editor to see how a topic looks for each audience. This catches issues before they reach readers:

  • Content that accidentally has no conditions (appears everywhere when it should not)

  • Content that is conditioned on the wrong value

  • Use variable tokens in content that resolve to unexpected values in certain targets

  • Awkward transitions where a conditioned block is removed, leaving disjointed prose

Preview every audience variant before publishing.

Do not skip testing the "default" or most common audience. It is tempting to only preview the specialized outputs (admin, enterprise), but errors in the shared content affect everyone.

One source, N outputs

The power of this model is that you maintain shared content once. When you update a shared paragraph, every output gets the update on the next Publish a web site. When you fix a conditioned block, only the relevant audience is affected.

The tradeoff is upfront complexity. Setting up filter groups, Create variable sets, and Publication target settings takes planning. But for any team producing documentation for more than one audience, the alternative (maintaining separate copies that drift apart) is worse.

See also

Was this page helpful?