A Call For Simplifying Single Sourcing in Product Documentation

Discover how simplifying single sourcing in your product documentation can save time, reduce complexity, and improve collaboration across teams.

Designed by vectorjuice / Freepik

Single sourcing sounds like the holy grail of product documentation, right? A single source of truth, reduced maintenance headaches, and streamlined content updates across statically generated sites and content management platforms (CMS). It works in theory, but in practice, it’s often more complicated than it seems.

If you’ve ever tried to single-source product documentation, especially across multiple SDKs and repositories, you’ve probably encountered more headaches than you'd expect. Sometimes, it's not the effortless solution we hope for, but actually a series of challenges that make us question whether it's worth the effort.

To better understand the challenges and nuances of single sourcing, it’s helpful to first look at the definition of single-source publishing. Essentially, single sourcing involves maintaining content in one place and then distributing or referencing it across various locations or systems.

For example, in the Datadog documentation, we use a pull_config.yamlfile to pull in specific files from external repositories, like the one below, to sync our documentation across systems:

- repo_name: synthetics-test-automation-bitrise-step-upload-application
  contents:
  - action: pull-and-push-file
	branch: main
	globs:
	- 'README.md'
	options:
  	dest_path: '/continuous_testing/cicd_integrations/'
  	file_name: 'bitrise_upload.md'
  	front_matters:
    	dependencies: ["https://github.com/DataDog/synthetics-test-automation-bitrise-step-upload-application/blob/main/README.md"]
    	title: Continuous Testing and Bitrise

In this case, we single-source a lot of CI/CD provider README files for our Continuous Testing documentation, including tools like the following:

• Azure DevOps Extension

• CircleCI Orb

• GitHub Actions

• GitLab

• Jenkins

• Bitrise (Upload Application)

• Bitrise (Run Tests)

By referencing external files like this, we ensure that we always pull in the most up-to-date information without having to manually copy and paste content from these repositories. However, as convenient as this can be, it introduces complexity and makes things fragile.

Every time a file changes, it can break our docs build system—especially when something as simple as a link format is off, an anchor is incorrectly referenced, or a file isn’t synced properly. This is just one example of why we’ve had to reconsider our approach to single sourcing.

Let me walk you through my journey with single sourcing, and how I learned the hard way that it’s not always the best solution for scaling documentation.