# A Call For Simplifying Single Sourcing in Product Documentation

<figure><img src="/files/rEa2cES3Z5QdocrkewpU" alt=""><figcaption><p>Designed by vectorjuice / Freepik</p></figcaption></figure>

[Single sourcing](https://www.madcapsoftware.com/blog/guest-post-justifying-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.&#x20;

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](https://en.wikipedia.org/wiki/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.yaml`[file](https://github.com/DataDog/documentation/blob/master/local/bin/py/build/configurations/pull_config.yaml) to pull in specific files from external repositories, like the one below, to sync our documentation across systems:

```yaml
- 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](https://docs.datadoghq.com/continuous_testing/cicd_integrations/#integrations), 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.&#x20;

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.&#x20;

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.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.austin-lai.com/blog/a-call-for-simplifying-single-sourcing-in-product-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.