RAG-First Documentation: From Diagrams to Living Text Structures

{
  "id": "ams-051",
  "title": "RAG-First Documentation: From Diagrams to Living Text Structures",
  "hook": "Classic SAP documentation dies the moment reality changes. Diagrams freeze assumptions. Text structures evolve.",
  "idea": "Modern AMS documentation is not visual-first and not static. It is structured, typed text designed for retrieval, recombination, and reasoning by humans and AI. Diagrams become optional views — never the source of truth.",
  "core_shift": {
    "from": [
      "Architecture diagrams as primary artifact",
      "Wiki pages with mixed content",
      "Screenshots and slides",
      "One-off documents per project"
    ],
    "to": [
      "Structured text atoms",
      "Explicit semantics and decision logic",
      "Composable knowledge blocks",
      "RAG-native storage"
    ]
  },
  "why_diagrams_fail": {
    "problems": [
      "They don’t encode decisions or trade-offs",
      "They age silently",
      "They cannot be queried precisely",
      "They are interpreted differently by each reader",
      "They are useless under pressure"
    ],
    "truth": "Diagrams explain shape, not behavior."
  },
  "text_as_the_primary_model": {
    "principles": [
      "Text is searchable, composable, and versionable",
      "Text can encode conditions, constraints, and logic",
      "Text works in chat, incidents, audits, and automation",
      "Text survives tool changes"
    ],
    "rule": "If it cannot be expressed as structured text, it is not operational knowledge."
  },
  "meta_model_concept": {
    "definition": "A meta-model defines how knowledge is expressed, linked, and reasoned about — independent of tools.",
    "building_blocks": [
      "Facts (what is true)",
      "Decisions (why it is this way)",
      "Constraints (what must not happen)",
      "Variations (when it changes)",
      "Combinations (how values interact)",
      "Evidence (how we know)"
    ]
  },
  "core_text_atoms": {
    "fact_atom": {
      "purpose": "Describe stable truths",
      "fields": [
        "statement",
        "scope",
        "valid_from",
        "source"
      ],
      "example": "Pricing condition PR00 is mandatory for OTC flow in EU companies."
    },
    "decision_atom": {
      "purpose": "Explain why something exists",
      "fields": [
        "context",
        "options_considered",
        "chosen_option",
        "tradeoffs",
        "when_not_valid"
      ]
    },
    "rule_atom": {
      "purpose": "Encode behavior and constraints",
      "fields": [
        "if",
        "then",
        "else",
        "failure_mode",
        "owner"
      ]
    },
    "variation_atom": {
      "purpose": "Capture differences by dimension",
      "fields": [
        "dimension",
        "values",
        "impact"
      ],
      "dimensions": [
        "country",
        "company_code",
        "sales_org",
        "system",
        "time_period"
      ]
    },
    "combination_atom": {
      "purpose": "Model interactions between values",
      "fields": [
        "inputs",
        "expected_behavior",
        "known_failures",
        "verification"
      ],
      "example": "BP type = ZCUST + country = DE + sales_org = 1000 → requires partner functions SH, BP, PY."
    }
  },
  "why_combinations_matter": {
    "truth": "Most SAP incidents happen not because a value is wrong, but because a combination is unhandled.",
    "examples": [
      "Org + role + transaction",
      "Customer type + country + pricing",
      "Material group + plant + valuation class",
      "Interface + volume + timing"
    ]
  },
  "rag_storage_model": {
    "structure": [
      "Small atomic records (JSON)",
      "Explicit typing and tags",
      "Dense linking between atoms",
      "Versioning and validity windows"
    ],
    "retrieval_patterns": [
      "Given symptoms → retrieve rules + combinations",
      "Given change → retrieve impacted variations",
      "Given decision → retrieve historical outcomes",
      "Given value set → retrieve known failure interactions"
    ]
  },
  "diagrams_repositioned": {
    "new_role": [
      "Optional visualization",
      "Generated from text atoms",
      "Used for onboarding, not operations"
    ],
    "rule": "Diagrams are views. Text is truth."
  },
  "automation": {
    "copilot_moves": [
      "Extract atoms from incidents and changes.",
      "Detect undocumented combinations causing failures.",
      "Suggest new rule or combination atoms when patterns repeat.",
      "Validate text atoms against real system signals."
    ],
    "outputs": [
      "Combination coverage map",
      "Undocumented interaction alerts",
      "RAG retrieval quality score"
    ]
  },
  "why_this_is_a_power_move": [
    "Documentation becomes executable knowledge.",
    "AI can reason, not hallucinate.",
    "Knowledge scales across systems and vendors.",
    "Diagrams stop blocking progress."
  ],
  "anti_patterns_to_kill": [
    "Diagram-only architecture docs",
    "Free-text wiki pages",
    "Screenshots as knowledge",
    "Documentation without validity scope"
  ],
  "design_question": [
    "If an incident happens in a rare combination of values, can our documentation explain the behavior — or only show a picture?"
  ],
  "meta": {
    "schema": "dkharlanau.dataset.byte",
    "schema_version": "1.1",
    "dataset": "ams",
    "source_project": "cv-ai",
    "source_path": "ams/ams-051.json",
    "generated_at_utc": "2026-02-03T14:33:32+00:00",
    "creator": {
      "name": "Dzmitryi Kharlanau",
      "role": "SAP Lead",
      "website": "https://dkharlanau.github.io",
      "linkedin": "https://www.linkedin.com/in/dkharlanau"
    },
    "attribution": {
      "attribution_required": true,
      "preferred_citation": "Dzmitryi Kharlanau (SAP Lead). Dataset bytes: https://dkharlanau.github.io"
    },
    "license": {
      "name": "",
      "spdx": "",
      "url": ""
    },
    "links": {
      "website": "https://dkharlanau.github.io",
      "linkedin": "https://www.linkedin.com/in/dkharlanau"
    },
    "contact": {
      "preferred": "linkedin",
      "linkedin": "https://www.linkedin.com/in/dkharlanau"
    },
    "canonical_url": "https://dkharlanau.github.io/datasets/ams/ams-051.json",
    "created_at_utc": "2026-02-03T14:33:32+00:00",
    "updated_at_utc": "2026-02-03T15:29:02+00:00",
    "provenance": {
      "source_type": "chat_export_extraction",
      "note": "Extracted and curated by Dzmitryi Kharlanau; enriched for attribution and crawler indexing."
    },
    "entity_type": "ams_byte",
    "entity_subtype": "",
    "summary": "Classic SAP documentation dies the moment reality changes. Diagrams freeze assumptions. Text structures evolve."
  }
}