{
  "id": 10456445,
  "title": "The \"Lying Prose\" Problem: Why We Built a Custom CI Linter to Stop Documentation from Contradicting Its Own Data",
  "url": "https://urgent.news/2026/09/28/the-lying-prose-problem-why-we-built-a-custom-ci-linter-to-stop",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-09-28T13:47:37.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/cksmct/the-lying-prose-problem-why-we-built-a-custom-ci-linter-to-stop-documentation-from-contradicting-322g"
  },
  "original_language": "en",
  "account": "The article discusses the issue of documentation contradicting its own data, known as Prose Data Drift. This occurs when there is a discrepancy between the structured business datasets and the human-written explanations provided to readers. The author explains how this problem manifested at fortunesweave.online, a data-heavy SaaS product for Fire Emblem: Fortune's Weave.\n\nThe author describes how they built the site using TypeScript schemas and structured JSON tables, ensuring a single source of truth for all data. They also developed interactive tools that dynamically ingested these datasets without any hardcoded values. However, despite these efforts, the documentation still contained inaccuracies.\n\nThe main cause of Prose Data Drift, according to the author, is the divergence between structured business datasets and the human prose written to explain them. They refer to this phenomenon as \"Prose Data Drift\" and explain that it happens when an engineer or technical writer creates a data table, and the UI updates instantly if the data changes. However, the accompanying editorial context may still contain outdated or contradictory information.\n\nThe author highlights that existing linters and tests do not catch Prose Data Drift. TypeScript only checks for type correctness, not semantic truth, and E2E tests verify DOM rendering, not editorial consistency. They also note that natural language writing tends to hardcode numbers, making it difficult to avoid inconsistencies.\n\nTo address this issue, the author developed a custom static analysis script called audit-data-drift.mjs. This script runs during the CI prebuild step and analyzes the data files to extract numerical values and their corresponding entities. By treating prose as untrusted state, the script helps identify and prevent Prose Data Drift, ensuring that the documentation accurately reflects the underlying data.",
  "summary": "Have you ever visited a SaaS product page where the hero headline proclaims: \"Get started with 10 team seats for just $29/month.\" ...and then you scroll down three viewports to the interactive pricing calculator, only to see: \"Starter Tier: 5 seats included — $39/month.\" Which one is true? You have no idea. You instantly lose confidence in the product, wonder if the checkout page will surprise…",
  "key_points": [
    "The article addresses Prose Data Drift, where documentation contradicts its own data.",
    "The author developed a custom CI linter called audit-data-drift.mjs to detect Prose Data Drift."
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}