Technical Writing and Documentation 101: Content Reuse and Single‑Sourcing (Variables, Snippets, Conditional Text)

Content Reuse and Single‑Sourcing (Variables, Snippets, Conditional Text)

Content Reuse & Single-Sourcing: A Practical Study Guide

For aspiring technical writers, developers transitioning into writing, and writers modernizing their skills

What This Is

Content reuse and single-sourcing mean writing content once and reusing it across multiple documents, formats, or outputs—like a single API description appearing in a reference guide, a tutorial, and a CLI help command. This saves time, reduces errors, and keeps docs consistent. Real-world example: A payment gateway API (e.g., Stripe) might reuse the same "Create a Charge" endpoint description in: - The API reference (Swagger UI) - A getting-started guide (Markdown in GitHub) - A CLI tool’s --help output (man pages) - A mobile SDK’s inline docs (Javadoc/Doxygen)

Without reuse, you’d manually update the same info in four places—guaranteeing drift and frustration.

Key Terms & Tools

• Single-sourcing: Writing content in one place (e.g., a Markdown file or DITA topic) and publishing it to multiple outputs (HTML, PDF, help systems). Tools: MadCap Flare, Oxygen XML, Sphinx, Docusaurus.
• Variables: Placeholders for text that changes across outputs (e.g., {{product_name}} becomes "Stripe" in one doc and "PayPal" in another). Tools: Markdown (Liquid/Jinja2), DITA, AsciiDoc.
• Snippets (includes/reusables): Reusable blocks of text (e.g., a "Prerequisites" section or a curl example). Tools: Markdown (includes), DITA conrefs, Sphinx .. include::, GitHub/GitLab snippets.
• Conditional text (profiling): Content that appears only in certain outputs (e.g., "Linux-only" steps hidden in Windows docs). Tools: DITA @props, MadCap Flare conditions, AsciiDoc ifdef.
• Docs-as-Code: Treating docs like code—stored in Git, built with static site generators (SSGs), reviewed via pull requests. Tools: Hugo, Docusaurus, MkDocs, GitHub/GitLab CI.
• OpenAPI (Swagger): A spec for REST APIs that auto-generates docs (e.g., Swagger UI, ReDoc). Tools: Swagger Editor, Stoplight, Redocly.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular, reusable docs. Tools: Oxygen XML, FrameMaker, easyDITA.
• Markdown: A lightweight markup language for docs-as-code. Tools: VS Code (with extensions), GitHub, Hugo.
• Static Site Generators (SSGs): Tools that build docs from Markdown/AsciiDoc into HTML. Examples: Docusaurus (React-based), MkDocs (Python), Hugo (Go).
• Component Content Management System (CCMS): A database for storing and reusing doc components. Tools: Paligo, IXIASOFT, easyDITA.
• Liquid/Jinja2: Templating languages for variables and logic in Markdown/HTML. Example: {% if user.role == "admin" %}...{% endif %}.
• Conref (DITA): A "content reference" to reuse a DITA element (e.g., a <step> in multiple tasks).

Step-by-Step / Process Flow

How to Implement Content Reuse in a Docs-as-Code Project

1. Audit your content
2. Identify repeated text (e.g., API descriptions, prerequisites, error messages).

3. Example: Search for "404 Not Found" in your docs—it likely appears in 5+ places.

4. Choose a reuse method

5. For Markdown: Use includes (e.g., {% include "snippets/prerequisites.md" %} in Jekyll) or variables (e.g., {{site.product_name}}).
6. For DITA: Use conrefs or keyrefs.

7. For OpenAPI: Define reusable schemas (e.g., ErrorResponse used in 20 endpoints).

8. Extract reusable content

9. Move repeated text into standalone files (e.g., snippets/api-auth.md).

10. Example: A curl example for authentication:
    markdown
# snippets/auth-curl.mdbash
    curl -X POST {{api_base_url}}/auth \
    -H "Authorization: Bearer {{api_key}}"
    

11. Add variables/conditions

12. Replace hardcoded values with variables (e.g., {{api_base_url}}).

13. Add conditions for platform-specific content (e.g., {% if target == "linux" %}...{% endif %}).

14. Test the output

15. Build docs locally (e.g., npm run build for Docusaurus) and verify:

    
    
    • Variables render correctly.
    • Includes appear in the right places.
    • Conditional text is hidden/shown as expected.

16. Automate updates

17. Use Git hooks or CI/CD (e.g., GitHub Actions) to rebuild docs on changes.
18. Example: A GitHub Action that runs mkdocs build on every push to main.

Common Mistakes

• Mistake: Hardcoding values (e.g., https://api.stripe.com/v1) instead of using variables.
  Correction: Use {{api_base_url}} so you can update it in one place (e.g., for staging vs. production). Why: Avoids manual find-and-replace across 100 files.

• Mistake: Creating "Frankenstein snippets" (e.g., a "Prerequisites" snippet that’s 80% reusable but needs tweaks for each guide).
  Correction: Break snippets into smaller, atomic chunks (e.g., prerequisites-python.md, prerequisites-node.md). Why: Smaller snippets are easier to reuse and maintain.

• Mistake: Overusing conditions (e.g., @props="linux,windows,mac" on every paragraph).
  Correction: Group related content into conditional blocks (e.g., a single <div> for Linux-only steps). Why: Too many conditions make docs unreadable and slow to build.

• Mistake: Not documenting reuse rules (e.g., "Don’t edit this file—it’s included in X, Y, Z").
  Correction: Add a comment at the top of reusable files:
  ```markdown
  <!--
  WARNING: This snippet is reused in:

  
  
  • /docs/getting-started.md
  • /docs/cli/help.md Edit here to update all instances.
    --> ```

• Mistake: Ignoring tool limitations (e.g., trying to use DITA conrefs in Markdown).
  Correction: Match the reuse method to your toolchain (e.g., Markdown → includes/variables; DITA → conrefs). Why: Avoids broken builds and frustration.

Tech Writing Interview / Portfolio Tips

• Hiring managers evaluate:
• Can you explain reuse tradeoffs? (e.g., "Snippets reduce duplication but add complexity—when would you not use them?")
• Do you know tool-specific quirks? (e.g., "How do you reuse content in Docusaurus vs. Sphinx?")

• Can you debug reuse issues? (e.g., "A snippet isn’t rendering in the PDF output—how do you fix it?")

• Portfolio tips:

• Show reuse in action: Include a GitHub repo with:
  • A Markdown project using includes/variables (e.g., a snippets/ folder).
  • An OpenAPI spec with reusable schemas (e.g., components/schemas/Error).
• Highlight automation: Add a CI/CD pipeline (e.g., GitHub Actions) that builds docs with reused content.

• Explain your choices: In a README, describe why you used snippets vs. variables for a specific case.

• Tricky distinctions to know:

• Snippets vs. Variables: Snippets reuse blocks of content (e.g., a paragraph); variables reuse values (e.g., a product name).
• DITA conrefs vs. Markdown includes: Conrefs are XML-based and support conditions; includes are file-based and simpler.
• OpenAPI components vs. DITA conrefs: Both enable reuse, but OpenAPI is for APIs, while DITA is for general docs.

Quick Check Questions

1. Scenario: A developer updates an API endpoint but forgets to update the docs. The docs use snippets for endpoint descriptions. How do you ensure the docs stay in sync?
   Answer: Store the snippet in the same repo as the code (e.g., api-docs/snippets/endpoint.md) and add a pre-commit hook or CI check to verify the snippet matches the OpenAPI spec. Why: Co-locating docs and code reduces drift.

2. Scenario: Your team wants to publish the same guide for Linux, Windows, and macOS, but 20% of the content is platform-specific. How do you structure the docs?
   Answer: Use conditional text (e.g., DITA @props or AsciiDoc ifdef) to hide/show platform-specific sections. Why: Single-sourcing avoids duplicating 80% of the content.

3. Scenario: A writer complains that snippets make docs harder to edit because they have to jump between files. How do you respond?
   Answer: Balance reuse with readability—use snippets for truly repeated content (e.g., API descriptions) but inline unique content. Add clear comments linking to included files. Why: Overusing snippets can fragment docs.

Last-Minute Cram Sheet

1. Markdown includes: {% include "snippets/example.md" %} (Jekyll) or .. include:: snippets/example.md (Sphinx).
2. Variables in Markdown: {{product_name}} (Jinja2) or {{ site.title }} (Jekyll).
3. DITA conref: <step conref="tasks/common.dita#common/step1"/>
4. OpenAPI reusable schema: Define in components/schemas/ and reference with $ref.
5. Conditional text in AsciiDoc: ifdef::linux[] ... endif::linux[]
6. Docs-as-code tools: Docusaurus (React), MkDocs (Python), Hugo (Go).
7. ⚠️ Don’t reuse content that’s almost the same—break it into smaller snippets.
8. ⚠️ OpenAPI 3.0 vs. 2.0: 3.0 supports reusable components; 2.0 uses definitions.
9. GitHub/GitLab snippets: Store reusable text in repo snippets or a snippets/ folder.
10. CI/CD for docs: Use GitHub Actions to auto-build docs on git push. Example:
    ```yaml
    • name: Build docs run: npm run build ```