The Problem with Traditional Tech Pubs

Most technical documentation organizations in the semiconductor and software industry are running pipelines designed for a simpler time. Engineers generate HTML from Doxygen and email it to writers. Register maps are maintained in spreadsheets and hand-copied into Word. API tables drift out of sync with the codebase within weeks of a release. Product names and version numbers live in someone's head — or worse, in a slide deck. The consequences are well understood: customer support escalations driven by documentation errors, delayed customer bring-up, compliance gaps in regulated markets, and doc teams perpetually running behind engineering.

"The most expensive documentation is the kind that's almost right." — A principle of modern structured authoring

The solution is not to ask writers to work faster. It is to redesign the pipeline so that engineering truth flows into documentation automatically — and human writers focus their effort where it matters most: explanation, usability, and customer outcomes.

The Three-Layer Architecture

A modern tech pubs stack for semiconductor and software organizations should be understood as three distinct, interconnected layers. Conflating them is the single most common architectural mistake.

Each layer has distinct tooling, ownership, and quality gates. The architecture described in this paper connects all three — with Jama Connect anchoring Layer 1, Doxygen and JSON feeds populating Layer 2, and Adobe FrameMaker or AEM Guides managing Layer 3.

Source Systems: Where Truth Lives

Before a single doc topic is authored, it is essential to identify and respect the authoritative source for every category of technical content. In a semiconductor-plus-software environment, there are four primary truth sources.

Hardware Truth Sources

Silicon and packaging teams own the definitive facts about the device: register maps, IP block descriptions, pin assignments, package tables, electrical characteristics, supported interfaces, device variants and SKUs, errata inputs, and validation results. These typically exist as structured XML, JSON, or CSV exports from design systems — and should be treated as upstream source data, not as content that writers touch.

Software Truth Sources

Firmware and software repositories hold API signatures, CLI command definitions, struct and enum declarations, configuration schemas, sample code, and release manifests. Doxygen-style comments embedded in source code provide the extraction point for this content.

Writer-Authored Content

The high-value explanatory layer — concepts, procedures, bring-up guides, debug flows, troubleshooting trees, use-case tutorials, migration notes, and architecture overviews — is the domain where technical writers add irreplaceable value. This content is authored directly in DITA/XML within Adobe tooling.

Business and Release Metadata

Product names, version compatibility matrices, lifecycle status, publication permissions, audience classifications, and release dates provide the context that governs conditional publishing. These typically originate from program management systems and are best encoded as JSON or XML consumed by the build pipeline.

Doxygen as the Code-Doc Compiler

Doxygen should be thought of as the engineering team's documentation compiler. Just as a compiler transforms source code into executable binaries, Doxygen transforms annotated source code into structured, machine-readable reference content.

With GENERATE_XML=YES, Doxygen emits structured XML describing every function, class, struct, enum, typedef, and file-level object in the codebase. This output is the critical handoff point between the engineering world and the docs pipeline.

The key design principle is that Doxygen XML should feed downstream transformation — not be published directly as HTML for writers to copy from. Once Doxygen XML exists, XSLT or Python transforms convert it into DITA reference topics that become first-class members of the canonical doc repository.

The Canonical Content Model: DITA/XML

Despite the proliferation of Markdown-based documentation tools, DITA/XML remains the most appropriate canonical model for semiconductor and software documentation at scale. The reasons are structural, not sentimental.

Topic Architecture

A clean topic model for a semiconductor-plus-software product family should include: Concept (architecture background, what a block or feature is), Task (integration, configuration, validation, debug procedures), Reference (registers, APIs, pin tables, CLI options, limits), Troubleshooting (symptom/cause/fix patterns), Release Notes (versioned deltas), and Notices (legal, export, safety, handling).

Map Architecture

Output maps should be assembled by audience, not by topic origin. A single DITA topic can appear in the Hardware Integration Guide, the Field App Engineer Troubleshooting Manual, and the Internal Bring-Up Checklist — filtered and assembled appropriately for each.

The Role of JSON in the Pipeline

JSON is upstream fuel, not the final authoring model. It is most valuable as the source format for data that engineers naturally own and maintain — and that should never be hand-copied by writers.

A well-designed pipeline keeps engineers in JSON and code comments, transforms those inputs into DITA reference topics automatically, and reserves human writing effort for the narrative layer that machines cannot generate.

Adobe as the Authoring and Publishing Layer

Adobe's structured documentation products are built around the DITA/XML content model, making them the natural governance and delivery layer for this architecture. There are two primary deployment patterns.

Option A: Adobe FrameMaker

FrameMaker is the right choice for teams that need a powerful desktop authoring environment with strong PDF output, are working at smaller to medium scale, and are producing complex long-document deliverables such as hardware integration guides, register reference manuals, and qualification reports.

Option B: Adobe Experience Manager Guides

AEM Guides is the right choice for organizations operating at enterprise scale — multiple contributing teams, complex approval workflows, component reuse across a large product portfolio, and portal-based delivery to customers and partners.

The Transform and Normalization Layer

The transform layer is the connective tissue of the entire pipeline — the set of scripts, XSLT stylesheets, and validation tools that convert upstream source data into well-formed DITA topics ready for Adobe authoring.

A critical repository design decision: generated DITA topics should be stored separately from hand-authored topics. Generated files are build artifacts — they should be regenerated on every pipeline run and never hand-edited.

Conditional Publishing and Content Reuse

Conditional publishing is where the investment in structured content pays the most dividends — particularly for semiconductor companies managing product families with overlapping but distinct feature sets.

DITA's key, conref, and attribute-based conditionalization system allows a single authored source to produce multiple output variants without duplication. Typical conditions include audience (customer, partner, internal), platform (Linux, Windows, RTOS), silicon revision (A0, B0, C0), product variant, and release status (beta, GA, deprecated).

Where Jama Connect Fits

Jama Connect is the most powerful addition to the modern tech pubs stack that most documentation organizations are not yet using to its full potential. It belongs upstream of the pipeline, as the system that defines what the pipeline is responsible for documenting.

"Without a requirements system, your docs pipeline tells you what you wrote. With Jama integrated, your system tells you what you promised, what you built, what you verified, what you documented, and what you shipped." — Core principle of traceable documentation

What Jama Owns

In a semiconductor and software organization, Jama Connect is the authoritative system for product requirements (functional, performance, electrical, compliance), system decomposition and traceability from requirement to subsystem to IP block to firmware to driver, verification linkage connecting test cases to test results, and change management tracking requirement evolution across silicon revisions and software releases.

Integration Architecture

Requirements → Documentation Coverage

Jama exports requirements via API in JSON or XML format. The transform layer ingests this data and uses it to automatically generate requirements appendices, compliance trace tables, and feature coverage matrices.

Traceability → Completeness Enforcement

Pipeline validation rules can enforce that every customer-visible GA requirement has at least one DITA topic reference, and that every documented feature maps to an active requirement. This eliminates ghost features in documentation and undocumented shipped capabilities.

Release Gating

In a mature integration, documentation publishing can be gated on Jama status. A GA publish run only succeeds when all GA requirements are approved, all critical test cases are passed, and no blocking defects remain open.

CI/CD Pipeline Design

A modern tech pubs pipeline should be treated as a software build system — triggered automatically, validated at every stage, and producing reproducible, versioned output artifacts.

pipeline:
  stages:
    - extract_code_docs
    - ingest_hw_data
    - ingest_jama_requirements
    - transform_to_dita
    - validate_content
    - assemble_maps
    - publish_outputs

validate_content:
  checks:
    - json_schema
    - xml_schema
    - dita_link_check
    - metadata_consistency
    - jama_coverage_completeness  # fails if GA req has no doc ref
    - undocumented_public_api       # fails if API has no DITA topic

assemble_maps:
  variants:
    - public
    - internal
    - partner
    - product_A0
    - product_B0
    - sdk_5_0

Validation Gates

A modern pipeline should fail — loudly and specifically — when documentation truth is broken. Validation gates are the mechanism that enforces this and should be treated as first-class pipeline stages, not optional checks.

Versioning in a Matrixed Environment

Semiconductor documentation versioning is not a linear problem. Content truth is matrixed across at least five dimensions simultaneously: silicon revision, board revision, firmware version, SDK version, and document bundle release. A pipeline that does not explicitly model this matrix will produce documentation that is always subtly wrong for some subset of the product family.

The recommended approach is a compatibility manifest — a structured JSON file that defines the exact intersection of versions that a given documentation build represents.

{
  "product": "ABCD-200",
  "silicon_revs": ["A1", "B0"],
  "firmware_version": "2.3.1",
  "sdk_version": "5.0.0",
  "doc_bundle_version": "2026.04",
  "jama_baseline": "GA-2026-Q2",
  "audience_variants": ["public", "internal", "partner"]
}

Roles and Handoffs

The pipeline succeeds when roles are clearly defined and the core principle — engineering truth should not be manually transcribed by writers — is genuinely enforced.

Recommended Implementation Path

Organizations should resist the temptation to build the full architecture in a single program. A phased approach delivers value quickly while building toward the complete vision.

Phase 1: Foundation (30–60 Days)

Establish the minimum viable pipeline: Git for all source inputs, Doxygen configured with XML output, a Python-based transform for Doxygen XML to DITA, a DITA repository structure with generated and authored directories separated, and FrameMaker for authoring and PDF output. Automate only API reference and release notes in this phase.

Phase 2: Hardware Data Automation (60–90 Days)

Add structured hardware data ingestion: register JSON/XML transforms to DITA reference topics, device variant matrix automation, and compatibility manifest driving conditional publishing. Introduce validation gates for schema compliance and link checking.

Phase 3: Jama Integration (90–120 Days)

Connect Jama Connect via API export. Implement requirements-to-doc coverage checks. Add Jama-driven metadata tagging to DITA topics. Build the coverage completeness validation gate. Begin generating compliance trace tables automatically.

Phase 4: Scale and Governance (120+ Days)

Evaluate AEM Guides if team scale or portal delivery requirements justify it. Implement release gating tied to Jama status. Expand conditional publishing variants. Add translation workflow integration. Establish full bidirectional traceability: requirement ↔ doc topic ↔ test case ↔ release artifact.

"The goal is a pipeline where engineering truth flows into documentation automatically, writers focus their energy on explanation and customer outcomes, and every published deliverable can be traced back to a verified requirement." — Simon Bennett, AI Tech Sales

This paper represents a practitioner perspective on modern technical publications architecture. Specific toolchain configurations, integration patterns, and build specifications should be validated against organizational context, team capabilities, and product requirements before implementation. Tool capabilities and product features referenced reflect the state of the market as of April 2026.