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.

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 per 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's often cleaner to split it into separate topics and share the common parts through How component reuse works.

Identifying your dimensions

A dimension is an axis along which your content varies. Common dimensions:

  • Audience — admin vs. end user, developer vs. non-technical

  • Platform — Windows vs. macOS vs. Linux

  • Product tier — free vs. paid, standard vs. enterprise

  • Region — geographic or regulatory differences

Most documentation teams need one or two dimensions. Three is unusual. If you're 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's 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. Every conditioned block must be reviewed during every edit pass to ensure it's 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 (e.g., "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, etc.).

  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"]
}
{
  "Audience": ["End User"]
}

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 shouldn't)

  • Content that's 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.

Don't skip testing the "default" or most common audience. It's 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 shared content is maintained 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 dimensions, 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?