Technical storytelling: one architecture, five audiences

#The 60-second version

A forward deployed engineer explains the same AI solution many times a week. The CIO, the business process owner, a developer, the SAP architect and the security team all need to hear about it. Each asks a different question:

• CIO: Is it worth it, is it safe, and does it fit our direction?
• Process owner: What changes for my people on Monday?
• Developer: What do I build, call and test?
• SAP architect: Where does it live, and what does it touch in SAP?
• Security team: What data goes where, under whose permissions, and what can go wrong?

Technical storytelling means answering each of those questions from one set of facts. You choose a different picture, different numbers and a different request for each reader. The facts never change between versions. If the CIO hears "350 hours a month" and the process owner hears "about 400", trust is gone for both.

Every version has the same five parts: a headline with the answer first, one picture, the numbers that decide their question, the risks they own, and one ask.

The full, written design still lives in one place: the solution design document. The five stories are short views of it, cut for each reader, not replacements for it.

#Why it matters to the business

AI projects rarely stall because the model fails. They stall because an approver heard the wrong story. The CIO got a model diagram and couldn't see the value. The security team got a business case and couldn't see the data flow. The process owner heard "automation" and pictured job cuts.

Take the course's running example. The blocked sales orders assistant has just finished its two-week pilot, as described in Rapid prototyping. In the made-up pilot data:

• Analysts with the assistant took a median of 12 minutes per order; analysts without it took 15.5.
• The target was 10 minutes. The pilot got 64% of the way there, so gate 3 said ITERATE.
• 35 of 40 test cases passed, with no critical failures.
• Model cost was 0.031 EUR per order.

Now the team needs five things at once: budget for another round from the CIO, analysts from the process owner, fixes from the developers, the architect's sign-off on the design, and a security review. One deck for everyone serves no one. Five unconnected decks drift apart within a week.

Good storytelling also protects the business. It forces the team to state the miss plainly: 64% of the target, not "a success". Decisions made on a polished half-truth come back as failed rollouts.

#How SAP does it

None of the SAP sources opened for this topic offers a storytelling method for AI projects. As of October 2026, SAP does offer material that makes each audience's version easier to build and easier to trust:

• Diagram levels. SAP's BTP solution diagram guideline sorts diagrams by level of detail. draw.io's summary of it describes level 0 as an overview for executives, and level 1 for roles such as product managers, enterprise architects and use case owners. Level 2 adds technical detail such as identities, API calls and firewalls. SAP Architecture Center recommends draw.io with the guideline's shapes for landscapes, and Mermaid for process flows.
• Reference architectures. SAP Architecture Center publishes reference architectures, such as one for generative AI on SAP BTP with CAP and SAP AI Core. Starting from it gives SAP architects a picture they already know.
• Process models. SAP Signavio Process Manager lets process owners model processes in BPMN. If the customer already has a model of the order-to-cash process, show the change on it.
• Answers for the security team. SAP Learning's "Building Confidence in AI with SAP" course states that customer data is not used for training by external model providers when SAP uses their models. SAP's security course adds that customers remain ultimately responsible for legal requirements, personal data and oversight.
• Responsible AI. SAP describes its own Global AI Ethics Policy and human-in-the-loop design. That gives the CIO and compliance a shared vocabulary for oversight.

Choosing what each audience hears, and keeping the five versions consistent, is the forward deployed engineer's job.

#The five audiences at a glance

Two rules make the table work:

• Headline first. Lead with the answer, including bad news. "64% of the way to target" goes in the first sentence, not on slide nine.
• One ask per audience. If you can't say what you want from this person, you aren't ready to meet them.

#Questions to ask

When your team prepares a stakeholder update:

• Where is the single source for our numbers, and does every version use it?
• What is the headline for this audience, in one sentence?
• Which picture does this person already know: a process model, an SAP reference architecture, a landscape diagram?
• What decision or action do we want from this meeting?
• What is the worst news in this update, and is it in the headline?

When a partner or vendor presents to you:

• Show me the same numbers you showed my security team. Do they match?
• What did the pilot miss, and by how much?
• Which risks does my team own after go-live, and which does yours?
• Which statements about SAP's data handling come from SAP documents, and from which date?

#Common misconceptions

• "Simplifying for executives means leaving out the problems." It means leaving out the mechanics. The problems, and who owns them, stay in.
• "One deck with backup slides covers every audience." Each audience needs a different first slide. Backup slides answer follow-up questions; they don't change what the reader sees first.
• "Security just needs the architecture diagram." They need the data flow: which fields leave which system, under whose permissions, and what is logged.
• "Developers don't need the business numbers." Developers who know the target and the cost per case make better trade-offs than developers who only know the ticket.
• "Good storytelling is spin." Spin changes the facts per audience. Storytelling changes the order and the language, never the facts.

#Key terms

All course terms, A to Z, in the glossary

• Technical storytelling: explaining one solution to several audiences, each with the picture, numbers, risks and ask that fit their decision.
• Single source of truth: one place that holds the solution's facts and numbers. Every version of the story draws from it.
• Headline: the first sentence of an update, stating the answer and any bad news.
• View: one audience's picture of the solution, showing some parts and leaving out others.
• Diagram level: how much technical detail a diagram shows. SAP's guideline runs from an executive overview to detailed technical views.
• Ask: the one decision or action you want from this audience.
• Trust boundary: a line in a diagram where data passes from one owner's control to another's, such as from the SAP system to a model provider.

#Check yourself

#Mental model

One model of the solution, many views of it. A view may leave facts out and translate them, but it never adds or changes one.

The C4 model makes the same point about diagrams. A system context diagram shows one system with its users and neighbours, and its audience is everybody, technical or not. A container diagram zooms into the same system for architects, developers and operations staff. Both are views of one model, at different zoom levels.

Storytelling applies that idea to everything you say about a solution, not only the pictures:

In a real project, the facts come from the solution design document and the evidence of each prototype gate. The design document is the long form for reviewers who read everything; the briefs are the short forms for everyone else.

If two briefs disagree, one of them is wrong. If a brief needs a number the facts file doesn't hold, add it to the facts file first. That rule is what lets you tell five stories without telling five different truths.

#How it works

flowchart LR
  E[Evidence: eval results, pilot log, design doc] --> F[(Facts file)]
  F --> D[Derived numbers]
  F & D --> B1[CIO brief]
  F & D --> B2[Process owner brief]
  F & D --> B3[Developer brief]
  F & D --> B4[SAP architect brief]
  F & D --> B5[Security brief]
  B1 & B2 & B3 & B4 & B5 --> C{Check against facts}

#Step 1: Know the reader

Google's technical writing course starts every document by defining the audience. It warns that a role is only a first approximation: two architects can know very different things. It also names the trap experts fall into, the curse of knowledge: forgetting what a newcomer doesn't know. The wider the audience, the more you must explain, and the simpler the words should be.

For each audience, write down four things before you write a word:

#Step 2: Put the headline first

Each brief opens with one sentence that answers the reader's question. The rest of the brief supports it. If the news is bad, it goes in the headline: "The pilot saved 3.5 minutes per order, 64% of the way to the target." A reader who stops after one sentence should still have the truth.

#Step 3: Choose one picture per reader

Each audience gets one diagram, the one that answers their question. SAP's diagram guidance and C4 point in the same direction:

SAP Architecture Center suggests draw.io with the BTP solution diagram shapes for landscapes, and Mermaid for process flows and sequence diagrams. For internal working briefs, Mermaid is enough. For a customer's architecture board, redraw the architect's view in the official shapes.

#Step 4: Show the numbers in the reader's unit

The same fact reads differently to each audience. Translate the unit, never the value:

Every number in every column comes from the facts file or is computed from it. That is what a reader can check.

#Step 5: Name the risks each reader owns

List risks by owner, not by severity alone. The CIO needs to know a risk exists and who owns it. The developer and the security team also need the control that handles it. A risk that appears in no brief has no audience, and in practice no owner.

#Step 6: End with one ask

The last line of every brief is the one thing you want from this reader. "Approve one more two-week pilot round" is an ask. "Let us know your thoughts" is not.

#Telling it live

Most of these briefs are spoken, not read. For a ten-minute slot, a simple order works: headline (30 seconds), picture (2 minutes), numbers (2 minutes), risks and owners (2 minutes), ask (30 seconds), then questions. If you can't answer a question, say so and name when you will. A guessed number in a meeting becomes a "fact" in someone's slide by Friday, and then your facts file is no longer the only source.

#Build it yourself: one set of facts, five checked briefs

You will build a command-line tool that reads one facts file about the blocked sales orders assistant, writes five briefs (one per audience), and checks them. The check catches what goes wrong when people edit briefs by hand: a number that isn't in the facts, jargon in a leader's brief, a missing risk owner, a missing ask, a brief that has grown too long.

Before you start: complete Set up your computer for this course and Set up for Unit 14. They create your orchestrate-course folder, its .venv and the unit14 folder. This script uses only Python's built-in modules, so there is nothing new to install, and it doesn't call a model.

flowchart LR
  S[sample] --> F[(story/solution.json)]
  F --> B[build]
  B --> R[story/briefs/*.md]
  R --> C[check]
  F --> C

#What you need

• Your course folder from the setup topics.
• About 40 minutes.
• No accounts and no cost. Every number in the sample is made up; the pilot numbers match the rapid prototyping sample.

#Step 1: Open your course folder

1. Open VS Code, choose File > Open Folder, and open orchestrate-course.

2. Open a terminal: Terminal > New Terminal.

3. If the prompt doesn't start with (.venv), turn it on:

   • Windows (PowerShell):

     Copy

     .venv\Scripts\Activate.ps1

   • macOS / Linux:

     Copy

     source .venv/bin/activate

4. Check that the unit14 folder exists:

   • Windows (PowerShell):

     Copy

     dir unit14

   • macOS / Linux:

     Copy

     ls unit14

   If you see an error saying the folder doesn't exist, create it with mkdir unit14.

#Step 2: Create the script

1. In VS Code, right-click the unit14 folder, choose New File, name it story_pack.py, paste the code below and save.

"""Story pack: one set of facts about an AI solution, five briefs for five audiences.

Audiences: cio, process (business process owner), developer, architect (SAP architect),
security (security and data protection team).

Commands:
  sample          write a made-up facts file for the blocked sales orders example
  facts           print the facts and the numbers derived from them
  brief AUDIENCE  print one brief to the terminal
  build           write all five briefs to the briefs folder next to the facts file
  check           check the briefs in that folder against the facts

Uses only Python's built-in modules. No account, no network.
"""
import argparse
import json
import re
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
DEFAULT_FACTS = HERE / "story" / "solution.json"
AUDIENCES = ["cio", "process", "developer", "architect", "security"]
LEADERS = {"cio", "process"}          # briefs that must avoid technical jargon
MAX_WORDS = {"cio": 260, "process": 300, "developer": 420, "architect": 420, "security": 420}
HEADLINE_MAX = 30
JARGON = ["LLM", "token", "tokens", "OData", "API", "APIs", "embedding", "RAG", "prompt", "prompts",
          "CAP", "p95", "latency", "orchestration", "inference", "vector", "JSON", "OAuth", "endpoint"]

# ---------------------------------------------------------------------------
# 1. The made-up facts file. Every number is invented for the exercise; the
#    pilot numbers match the course's rapid prototyping topic.
# ---------------------------------------------------------------------------
SAMPLE = {
    "name": "Blocked sales orders: context assistant",
    "status": "Pilot finished. Gate 3 said ITERATE: one more two-week round aimed at the time saving.",
    "problem": "Credit analysts spend a long time on each blocked sales order, mostly gathering context.",
    "solution": "The assistant drafts a context note for each blocked order from SAP data. "
                "The analyst still decides every release in SAP.",
    "currency": "EUR",
    "numbers": {
        "orders_per_month": 6000,
        "baseline_min": 17,
        "target_min": 10,
        "control_median_min": 15.5,
        "assisted_median_min": 12,
        "eval_cases": 40,
        "eval_passed": 35,
        "critical_failures": 0,
        "cost_per_order": 0.031,
        "slowest_draft_seconds": 6,
        "analysts_in_pilot": 5,
    },
    "reads": ["sales order header and items", "credit limit and exposure", "open items", "sales rep note"],
    "writes": "nothing: the assistant never changes SAP data",
    "personal_data": "the sales rep note can contain names; names are masked before the model sees the note",
    "risks": [
        {"id": "R1", "title": "A draft states a fact that is not in the data",
         "owner": "Tech lead", "for": ["cio", "process", "developer", "security"],
         "control": "every release stays an analyst decision; failing test cases rerun on every change"},
        {"id": "R2", "title": "Analysts stop reading drafts carefully",
         "owner": "Head of credit management", "for": ["cio", "process"],
         "control": "drafts show their sources; spot checks of released orders every month"},
        {"id": "R3", "title": "Text in a rep note tries to steer the model",
         "owner": "Security lead", "for": ["developer", "security"],
         "control": "note text is treated as data; output is checked; the assistant has no tool that writes"},
        {"id": "R4", "title": "Names in rep notes reach the model",
         "owner": "Data protection officer", "for": ["architect", "security"],
         "control": "masking before the model call; logs keep case numbers, not note text"},
        {"id": "R5", "title": "The model is retired by its provider",
         "owner": "SAP architect", "for": ["cio", "developer", "architect"],
         "control": "test set reruns on the replacement model before any switch"},
    ],
    "asks": {
        "cio": "Approve one more two-week pilot round with the same five analysts and the same budget.",
        "process": "Name the analysts for round 2 and confirm that every release stays an analyst decision.",
        "developer": "Fix the failing test cases first, then rerun the full set before round 2 starts.",
        "architect": "Confirm the read-only list of SAP data and the model replacement test.",
        "security": "Review the masking of rep notes and the steering tests before round 2 starts.",
    },
}

# ---------------------------------------------------------------------------
# 2. Derived numbers: computed once, used by every brief and by the check
# ---------------------------------------------------------------------------

def load(path):
    path = Path(path)
    if not path.exists():
        raise SystemExit(f"ERROR  facts file not found: {show(path)}. Run the sample command first.")
    try:
        facts = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        raise SystemExit(f"ERROR  {show(path)} is not valid JSON: line {e.lineno}, column {e.colno}: {e.msg}")
    for key in ["name", "status", "solution", "numbers", "risks", "asks", "currency"]:
        if key not in facts:
            raise SystemExit(f"ERROR  {show(path)} has no \"{key}\" entry")
    needed = ["orders_per_month", "baseline_min", "target_min", "control_median_min", "assisted_median_min",
              "eval_cases", "eval_passed", "critical_failures", "cost_per_order"]
    missing = [k for k in needed if k not in facts["numbers"]]
    if missing:
        raise SystemExit(f"ERROR  \"numbers\" is missing: {', '.join(missing)}")
    for r in facts["risks"]:
        bad = [a for a in r.get("for", []) if a not in AUDIENCES]
        if bad:
            raise SystemExit(f"ERROR  risk {r.get('id')} names unknown audiences: {', '.join(bad)}")
    return facts


def derive(n):
    saved = n["control_median_min"] - n["assisted_median_min"]
    gap = n["control_median_min"] - n["target_min"]
    return {
        "saved_min_per_order": round(saved, 2),
        "hours_saved_per_month": round(saved * n["orders_per_month"] / 60),
        "pass_rate_pct": round(100 * n["eval_passed"] / n["eval_cases"]),
        "failed_cases": n["eval_cases"] - n["eval_passed"],
        "share_of_target_pct": round(100 * saved / gap) if gap > 0 else 0,
        "min_still_to_target": round(n["assisted_median_min"] - n["target_min"], 2),
        "model_cost_per_month": round(n["cost_per_order"] * n["orders_per_month"]),
    }


def fmt(x):
    """6000 -> 6,000; 15.5 -> 15.5; 12.0 -> 12; 0.031 -> 0.031"""
    if isinstance(x, float) and not x.is_integer():
        return f"{x:,.3f}".rstrip("0").rstrip(".")
    return f"{int(x):,}"

# ---------------------------------------------------------------------------
# 3. The five briefs. Same facts, different question, picture, numbers and ask.
# ---------------------------------------------------------------------------

def risk_lines(facts, audience, with_control=True):
    lines = []
    for r in facts["risks"]:
        if audience in r.get("for", []):
            text = f"- **{r['title']}.** Owner: {r['owner']}."
            if with_control:
                text += f" Control: {r['control']}."
            lines.append(text)
    return lines or ["- None tagged for this audience."]


DIAGRAMS = {
    "cio": """flowchart LR
  A[Credit analyst] --> B[Context assistant on SAP BTP]
  B -->|reads only| C[SAP S/4HANA]
  B --> D[AI model through SAP AI Core]
  A -->|decides every release| C""",
    "process": """flowchart LR
  subgraph Analyst
    A1[Open blocked order] --> A2[Read the draft note] --> A3{Release?}
  end
  subgraph Assistant
    B1[Collect order, credit and rep note] --> B2[Draft the note]
  end
  A1 --> B1
  B2 --> A2
  A3 -->|yes or no, in SAP| A4[Order released or kept]""",
    "developer": """sequenceDiagram
  participant UI as Assistant panel
  participant App as CAP service
  participant S4 as S/4HANA OData
  participant AI as Orchestration
  UI->>App: draft(order)
  App->>S4: GET order, credit, items (user's rights)
  S4-->>App: fields
  App->>AI: template + masked fields
  AI-->>App: draft JSON
  App-->>UI: draft + sources""",
    "architect": """flowchart LR
  U[Analyst browser] --> W[CAP app on SAP BTP]
  W -->|released OData APIs, read only| S[SAP S/4HANA]
  W --> O[Generative AI hub orchestration]
  O --> M[Foundation model]
  W --> L[Logs: case number, cost, result]""",
    "security": """flowchart LR
  subgraph Customer SAP landscape
    S[S/4HANA data]
  end
  subgraph SAP BTP subaccount
    W[Assistant app] --> K[Masking in orchestration]
  end
  subgraph Model provider
    M[Foundation model]
  end
  S -->|user's own authorizations| W
  K -->|masked fields only| M
  M -->|draft text, untrusted| W""",
}


def brief(facts, audience):
    n, d, cur = facts["numbers"], derive(facts["numbers"]), facts["currency"]
    title = {"cio": "CIO", "process": "business process owner", "developer": "developer",
             "architect": "SAP architect", "security": "security team"}[audience]
    out = [f"# {facts['name']}: for the {title}", ""]
    if audience == "cio":
        out += [f"**Headline:** The pilot saved {fmt(d['saved_min_per_order'])} minutes per order, "
                f"{fmt(d['share_of_target_pct'])}% of the way to the target: about "
                f"{fmt(d['hours_saved_per_month'])} hours a month for about {fmt(d['model_cost_per_month'])} "
                f"{cur} of model cost.", "",
                "## What it is", "", facts["solution"], "",
                "## The numbers", "",
                f"- Handling time: {fmt(n['assisted_median_min'])} minutes with the assistant against "
                f"{fmt(n['control_median_min'])} without, in the same weeks. Target: {fmt(n['target_min'])}.",
                f"- At {fmt(n['orders_per_month'])} orders a month, {fmt(d['saved_min_per_order'])} minutes "
                f"per order is about {fmt(d['hours_saved_per_month'])} hours of analyst time.",
                f"- Status: {facts['status']}",
                f"- Quality: {fmt(n['eval_passed'])} of {fmt(n['eval_cases'])} test cases pass, "
                f"with {fmt(n['critical_failures'])} critical failures."]
    elif audience == "process":
        out += [f"**Headline:** Your analysts keep every release decision; the assistant writes the context note, "
                f"and in the pilot their median time fell from {fmt(n['control_median_min'])} to "
                f"{fmt(n['assisted_median_min'])} minutes.", "",
                "## What changes for your team", "",
                "- The analyst opens a blocked order and finds a draft note with its sources.",
                "- The analyst checks the note, then releases or keeps the order in SAP, as today.",
                "- Nothing is released, changed or sent to the customer by the assistant.", "",
                "## The numbers", "",
                f"- {fmt(n['analysts_in_pilot'])} analysts used it in the pilot.",
                f"- {fmt(d['failed_cases'])} of {fmt(n['eval_cases'])} test notes had a mistake; "
                f"{fmt(n['critical_failures'])} could have led to a wrong release."]
    elif audience == "developer":
        out += [f"**Headline:** {fmt(d['failed_cases'])} of {fmt(n['eval_cases'])} evaluation cases fail; fix those, "
                f"keep the slowest draft under {fmt(n.get('slowest_draft_seconds', 0))} seconds and keep cost per order "
                f"near {fmt(n['cost_per_order'])} {cur}.", "",
                "## What it is", "",
                "A CAP service reads the order with the user's own SAP authorizations, fills a prompt template, "
                "calls the generative AI hub orchestration service with masking on, and returns a draft as JSON "
                "with the source fields it used.", "",
                "## The numbers", "",
                f"- Evaluation: {fmt(n['eval_passed'])} of {fmt(n['eval_cases'])} pass "
                f"({fmt(d['pass_rate_pct'])}%), {fmt(n['critical_failures'])} critical.",
                f"- Slowest draft in the pilot: {fmt(n.get('slowest_draft_seconds', 0))} seconds.",
                f"- Model cost: {fmt(n['cost_per_order'])} {cur} per order.",
                f"- Reads: {', '.join(facts.get('reads', []))}. Writes: {facts.get('writes', '')}."]
    elif audience == "architect":
        out += ["**Headline:** A side-by-side app on SAP BTP that reads S/4HANA through released APIs, "
                "writes nothing back, and reaches the model only through SAP AI Core.", "",
                "## Placement and dependencies", "",
                f"- Reads: {', '.join(facts.get('reads', []))}.",
                f"- Writes: {facts.get('writes', '')}.",
                "- Nothing is modified inside S/4HANA; see the design document for the clean core rating.",
                f"- Volume: {fmt(n['orders_per_month'])} orders a month; model cost about "
                f"{fmt(d['model_cost_per_month'])} {cur} a month at {fmt(n['cost_per_order'])} {cur} per order."]
    elif audience == "security":
        out += ["**Headline:** The assistant reads with each analyst's own SAP authorizations, sends only "
                "masked fields to the model, and has no way to change SAP data.", "",
                "## Data and access", "",
                f"- Data read: {', '.join(facts.get('reads', []))}.",
                f"- Personal data: {facts.get('personal_data', '')}.",
                f"- Writes: {facts.get('writes', '')}.",
                "- Model output is treated as untrusted text and shown to the analyst, never executed.",
                f"- Test results: {fmt(n['eval_passed'])} of {fmt(n['eval_cases'])} cases pass, "
                f"{fmt(n['critical_failures'])} critical."]
    out += ["", "## The picture", "", "```mermaid", DIAGRAMS[audience], "```", "",
            "## Risks you own or should know", ""]
    out += risk_lines(facts, audience, with_control=audience not in LEADERS)
    out += ["", f"**Ask:** {facts['asks'][audience]}", ""]
    return "\n".join(out)

# ---------------------------------------------------------------------------
# 4. The check: does each brief still tell the truth, to the right reader?
# ---------------------------------------------------------------------------
NUMBER = re.compile(r"(?<![\w/.-])\d[\d,]*(?:\.\d+)?(?![\w])")


def allowed_numbers(facts):
    values = set()

    def walk(x):
        if isinstance(x, bool):
            return
        if isinstance(x, (int, float)):
            values.add(round(float(x), 3))
        elif isinstance(x, str):
            for m in NUMBER.findall(x):
                values.add(round(float(m.replace(",", "")), 3))
        elif isinstance(x, dict):
            for v in x.values():
                walk(v)
        elif isinstance(x, list):
            for v in x:
                walk(v)
    walk(facts)
    walk(derive(facts["numbers"]))
    return values


def check_brief(text, audience, facts, allowed):
    checks = []   # (ok, message)
    body = re.sub(r"```.*?```", " ", text, flags=re.S)
    words = len(body.split())
    head = re.search(r"^\*\*Headline:\*\*(.*)$", text, flags=re.M)
    if head:
        hw = len(head.group(1).split())
        checks.append((hw <= HEADLINE_MAX, f"headline: {hw} words (max {HEADLINE_MAX})"))
    else:
        checks.append((False, "headline: no line starting with **Headline:**"))
    diagrams = len(re.findall(r"^```mermaid", text, flags=re.M))
    checks.append((diagrams == 1, f"picture: {diagrams} mermaid diagram(s) (need exactly 1)"))
    strays = []
    for line in text.splitlines():
        if line.startswith("#"):
            continue
        for m in NUMBER.findall(line):
            value = round(float(m.replace(",", "")), 3)
            if value not in allowed and not (value.is_integer() and value <= 10):
                strays.append(m)
    checks.append((not strays, "numbers: all match the facts" if not strays
                   else f"numbers: not in the facts file: {', '.join(sorted(set(strays)))}"))
    if audience in LEADERS:
        found = sorted({w for w in JARGON if re.search(rf"(?<![\w-]){re.escape(w)}(?![\w-])", text)})
        checks.append((not found, "jargon: none" if not found else f"jargon: {', '.join(found)}"))
    for r in facts["risks"]:
        if audience in r.get("for", []):
            ok = r["title"].lower() in text.lower() and r["owner"].lower() in text.lower()
            checks.append((ok, f"risk {r['id']}: {'named with its owner' if ok else 'missing, or owner missing'}"))
    ask = re.search(r"^\*\*Ask:\*\*\s*\S", text, flags=re.M)
    checks.append((bool(ask), "ask: present" if ask else "ask: no line starting with **Ask:**"))
    checks.append((words <= MAX_WORDS[audience], f"length: {words} words outside the diagram "
                                                 f"(max {MAX_WORDS[audience]})"))
    return checks

# ---------------------------------------------------------------------------
# 5. Commands
# ---------------------------------------------------------------------------

def show(path):
    try:
        return str(Path(path).resolve().relative_to(Path.cwd().resolve()))
    except ValueError:
        return str(path)


def cmd_sample(args):
    path = Path(args.dir) / "solution.json"
    if path.exists() and not args.force:
        print(f"{show(path)} already exists. Add --force to overwrite it.")
        return 1
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(SAMPLE, indent=2) + "\n", encoding="utf-8")
    print(f"Wrote {show(path)} (made-up facts for the blocked sales orders example).")
    print("Next: python unit14/story_pack.py facts")
    return 0


def cmd_facts(args):
    facts = load(args.facts)
    print(f"{facts['name']}\n{facts['status']}\n")
    print("Facts:")
    for k, v in facts["numbers"].items():
        print(f"  {k:<24} {fmt(v)}")
    print("Derived (computed by this script, used in every brief):")
    for k, v in derive(facts["numbers"]).items():
        print(f"  {k:<24} {fmt(v)}")
    print(f"Risks: {len(facts['risks'])}   Audiences: {', '.join(AUDIENCES)}")
    return 0


def cmd_brief(args):
    print(brief(load(args.facts), args.audience))
    return 0


def cmd_build(args):
    facts = load(args.facts)
    folder = Path(args.facts).resolve().parent / "briefs"
    folder.mkdir(exist_ok=True)
    existing = [a for a in AUDIENCES if (folder / f"{a}.md").exists()]
    if existing and not args.force:
        print(f"Briefs already exist in {show(folder)}: {', '.join(existing)}. "
              "Add --force to overwrite them (your edits will be lost).")
        return 1
    for a in AUDIENCES:
        (folder / f"{a}.md").write_text(brief(facts, a), encoding="utf-8")
    print(f"Wrote 5 briefs to {show(folder)}: " + ", ".join(f"{a}.md" for a in AUDIENCES))
    return 0


def cmd_check(args):
    facts = load(args.facts)
    folder = Path(args.facts).resolve().parent / "briefs"
    allowed = allowed_numbers(facts)
    failures = 0
    for a in AUDIENCES:
        path = folder / f"{a}.md"
        if not path.exists():
            print(f"== {a}.md\n  FAIL  file not found. Run the build command first.\n")
            failures += 1
            continue
        print(f"== {a}.md")
        for ok, message in check_brief(path.read_text(encoding="utf-8"), a, facts, allowed):
            print(f"  {'PASS' if ok else 'FAIL'}  {message}")
            failures += 0 if ok else 1
        print()
    print(f"Result: {len(AUDIENCES)} briefs, {failures} failure(s)")
    return 1 if failures else 0


def main(argv=None):
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = p.add_subparsers(dest="cmd", required=True)
    s = sub.add_parser("sample", help="write a made-up facts file")
    s.add_argument("--dir", default=str(DEFAULT_FACTS.parent), help="folder (default: unit14/story)")
    s.add_argument("--force", action="store_true", help="overwrite an existing facts file")
    for name, text in [("facts", "print facts and derived numbers"), ("brief", "print one brief"),
                       ("build", "write the five briefs"), ("check", "check the briefs")]:
        c = sub.add_parser(name, help=text)
        if name == "brief":
            c.add_argument("audience", choices=AUDIENCES)
        if name == "build":
            c.add_argument("--force", action="store_true", help="overwrite existing briefs")
        c.add_argument("--facts", default=str(DEFAULT_FACTS), help="facts file (default: unit14/story/solution.json)")
    args = p.parse_args(argv)
    handler = {"sample": cmd_sample, "facts": cmd_facts, "brief": cmd_brief,
               "build": cmd_build, "check": cmd_check}[args.cmd]
    return handler(args) or 0


if __name__ == "__main__":
    sys.exit(main())

#Step 3: Write the sample facts and look at them

1. Run:

   Copy

   python unit14/story_pack.py sample

2. You should see:

   Copy

   Wrote unit14/story/solution.json (made-up facts for the blocked sales orders example).
   Next: python unit14/story_pack.py facts

3. Run:

   Copy

   python unit14/story_pack.py facts

4. You should see the facts, then the numbers the script derives from them:

   Copy

   Blocked sales orders: context assistant
   Pilot finished. Gate 3 said ITERATE: one more two-week round aimed at the time saving.
   
   Facts:
     orders_per_month         6,000
     baseline_min             17
     target_min               10
     control_median_min       15.5
     assisted_median_min      12
     eval_cases               40
     eval_passed              35
     critical_failures        0
     cost_per_order           0.031
     slowest_draft_seconds    6
     analysts_in_pilot        5
   Derived (computed by this script, used in every brief):
     saved_min_per_order      3.5
     hours_saved_per_month    350
     pass_rate_pct            88
     failed_cases             5
     share_of_target_pct      64
     min_still_to_target      2
     model_cost_per_month     186
   Risks: 5   Audiences: cio, process, developer, architect, security

5. Open unit14/story/solution.json in VS Code. Look at the risks list: each risk has a title, an owner, a control, and a for list naming the audiences that must hear about it. The asks section holds one request per audience.

Notice that hours_saved_per_month assumes the assistant is used on all 6,000 orders. Say so when you show it, as the CIO brief does.

If you see already exists, you ran this before. Add --force to overwrite the facts file.

#Step 4: Build the five briefs

1. Run:

   Copy

   python unit14/story_pack.py build

2. You should see:

   Copy

   Wrote 5 briefs to unit14/story/briefs: cio.md, process.md, developer.md, architect.md, security.md

3. Open unit14/story/briefs/cio.md. It starts like this:

   Copy

   # Blocked sales orders: context assistant: for the CIO
   
   **Headline:** The pilot saved 3.5 minutes per order, 64% of the way to the target: about 350 hours a month for about 186 EUR of model cost.
   
   ## What it is
   
   The assistant drafts a context note for each blocked order from SAP data. The analyst still decides every release in SAP.
   
   ## The numbers
   
   - Handling time: 12 minutes with the assistant against 15.5 without, in the same weeks. Target: 10.
   - At 6,000 orders a month, 3.5 minutes per order is about 350 hours of analyst time.
   - Status: Pilot finished. Gate 3 said ITERATE: one more two-week round aimed at the time saving.
   - Quality: 35 of 40 test cases pass, with 0 critical failures.

4. Open security.md next. Same facts, different headline:

   Copy

   **Headline:** The assistant reads with each analyst's own SAP authorizations, sends only masked fields to the model, and has no way to change SAP data.

5. To see a diagram drawn, copy the lines between ```mermaid and ``` from any brief and paste them into the Mermaid Live Editor at https://mermaid.live.

Compare the five briefs. The CIO and process owner briefs list risks with their owners only. The other three also list the control for each risk, because those readers build or review it.

To print one brief without writing files, run python unit14/story_pack.py brief architect (or cio, process, developer, security).

#Step 5: Check the briefs

1. Run:

   Copy

   python unit14/story_pack.py check

2. You should see five blocks like this one, and a result line:

   Copy

   == cio.md
     PASS  headline: 26 words (max 30)
     PASS  picture: 1 mermaid diagram(s) (need exactly 1)
     PASS  numbers: all match the facts
     PASS  jargon: none
     PASS  risk R1: named with its owner
     PASS  risk R2: named with its owner
     PASS  risk R5: named with its owner
     PASS  ask: present
     PASS  length: 190 words outside the diagram (max 260)
   ...
   Result: 5 briefs, 0 failure(s)

The jargon line appears only for the CIO and process owner briefs. Words such as "API", "token", "prompt" or "latency" are fine for a developer and a barrier for a sponsor.

#Step 6: Break a brief on purpose

Briefs get edited by hand before meetings. This step shows what the check catches.

1. Open unit14/story/briefs/cio.md.

2. In the headline, change about 350 hours a month to about 400 hours a month.

3. In the first line under What it is, change The assistant drafts to The LLM assistant drafts.

4. Save the file and run:

   Copy

   python unit14/story_pack.py check

5. The CIO block now shows two failures:

   Copy

   == cio.md
     PASS  headline: 26 words (max 30)
     PASS  picture: 1 mermaid diagram(s) (need exactly 1)
     FAIL  numbers: not in the facts file: 400
     FAIL  jargon: LLM

   and the last line is Result: 5 briefs, 2 failure(s). The script also ends with exit code 1, so an automated pipeline would stop here.

6. Throw away your edits by rebuilding:

   Copy

   python unit14/story_pack.py build --force

Without --force, build refuses to overwrite briefs, so it can't silently erase the wording you improved.

#Step 7: Change a fact and see which briefs go stale

Facts change: the analysts timed a few more orders, and the control median moves.

1. Open unit14/story/solution.json and change "control_median_min": 15.5 to "control_median_min": 16. Save.

2. Run the check without rebuilding:

   Copy

   python unit14/story_pack.py check

3. Two briefs now fail:

   Copy

     FAIL  numbers: not in the facts file: 15.5, 3.5, 350, 64
     FAIL  numbers: not in the facts file: 15.5

   The first line is the CIO brief, the second the process owner brief. The developer, architect and security briefs never used those numbers, so they still pass. That is the list of people who need a corrected update.

4. Change the value back to 15.5, save, and rebuild:

   Copy

   python unit14/story_pack.py build --force
   python unit14/story_pack.py check

5. The last line should again be Result: 5 briefs, 0 failure(s).

#How the code works

The generated sentences are a first draft for the blocked orders example. Some sentences, such as "The analyst opens a blocked order", are written into the script rather than taken from the facts. For your own solution, rewrite those in your own words; the check makes sure the facts survive your rewrite.

#Use your own solution

1. Run python unit14/story_pack.py sample --dir unit14/my_story to get a starting file in a new folder.

2. Edit unit14/my_story/solution.json with your solution's facts. Keep the same entry names.

3. Run any command with --facts:

   Copy

   python unit14/story_pack.py build --facts unit14/my_story/solution.json
   python unit14/story_pack.py check --facts unit14/my_story/solution.json

#If something goes wrong

#The SAP way

Each audience has SAP material you can build on. Names and statements below are as of October 2026, from the sources listed.

#Diagrams in SAP's own conventions

• Levels. SAP's BTP solution diagram guideline sorts diagrams by detail. draw.io's summary describes level 0 as an overview for executives, level 1 for roles such as product managers, enterprise architects and use case owners, and level 2 for technical depth: certificates, identities, API calls, firewalls and protocols. SAP Architecture Center describes L1 as a high-level overview and L2 as detailed views of service interactions, data flows and integration points.
• Tools. SAP Architecture Center recommends draw.io with the BTP solution diagram shapes for landscapes, and Mermaid for process flows and sequence diagrams. draw.io ships an SAP shape library and suggests a legend and numbered steps along a path.
• Where to get it. SAP Architecture Center links the BTP solution diagram guideline, its starter kit and its draw.io shape libraries, published in SAP's btp-solution-diagrams repository on GitHub. Take the current version from there before an architecture board.

#Starting points per audience

#What SAP says, and what stays yours

Two statements are worth having ready for the security team, quoted with their source and date:

• In "Does AI Train on My Data?", SAP states that when it uses external foundation models, customer data is not used for model training or retraining by external providers. The same lesson says retention depends on the service and its configuration, and that customers stay responsible for storage, governance and deletion.
• In its security architecture course, SAP says customers are ultimately responsible for meeting legal requirements. It also leaves the oversight processes, the handling of personal data and keeping humans in the decision loop with the customer.

Your brief should never stretch these into "SAP handles security". The data flow, the masking, the authorizations and the logs in your design are your team's to explain.

#What SAP doesn't prescribe

None of the SAP sources opened for this topic offers a method for tailoring one solution's story to different audiences. The five-part brief, the audience table and the check are this course's.

#Build vs. SAP

A practical mix: keep the facts file and the briefs in Git next to the evidence, use Mermaid for working briefs, and redraw the architect's and security team's pictures in SAP's official shapes when they go to a customer's architecture board.

#Production concerns

A brief is not code, but it carries real customer facts into rooms and inboxes.

• Confidentiality. Briefs hold customer numbers and architecture details. Share them only with people who may see them. For your public portfolio, use the made-up sample, never a customer's facts.
• Provenance. Every number in the facts file should point to its evidence: the evaluation results, the pilot log, the cost log. Keep the facts file in Git next to them, so a number can be traced months later.
• Versioning. Regenerate and recheck the briefs after every gate or design change, and date them. A brief from before the pilot, forwarded after it, is a common source of wrong numbers.
• Security review is a review. The security brief opens the conversation; it doesn't replace the formal review, the authorization concept or the data protection assessment.
• Honest status. State misses, open risks and unverified claims plainly. If you quote SAP on data handling, quote the page and the date, because terms change.
• Accessibility. Don't rely on color alone in diagrams; label the arrows. Use simple words: many readers use English as a second language or a translation tool, as Google's writing course points out.

#Pitfalls

• One deck for all. Everyone sees slide one, and slide one answers one person's question.
• Numbers typed by hand. A number retyped into a slide drifts. Generate it from the facts or check it against them.
• Burying the miss. "Promising results" instead of "64% of the target" costs you the sponsor's trust when the full number surfaces.
• The architect's diagram for the CIO. Twenty boxes and protocol names lose the room. Give the CIO the context view.
• The CIO's diagram for security. A box labeled "AI" hides exactly what the security team needs: which fields leave, where they go and under whose identity.
• Risks without owners. A risk listed with no owner is a worry, not a plan.
• No ask. A meeting without an ask produces goodwill and no decision.
• Overclaiming SAP. "SAP guarantees our data is safe" isn't what SAP says. Quote what it says, and own the rest.

#Exercise

Write the facts file and the five briefs for your own solution, the one you prototyped in Rapid prototyping, and get them through the check.

1. Run python unit14/story_pack.py sample --dir unit14/my_story.

2. In unit14/my_story/solution.json, replace the name, status, solution, numbers, data read and written, personal data, risks and asks with your solution's facts. If you have no solution of your own, keep the blocked orders numbers but change the pilot results to those in your own unit14/my_prototype/decision.md.

3. Add at least one risk of your own, with an owner, a control and the audiences it is for.

4. Build the briefs:

   Copy

   python unit14/story_pack.py build --facts unit14/my_story/solution.json

5. Rewrite the CIO headline and the process owner headline in your own words. Rewrite every sentence that describes the blocked orders example if your solution is different. Keep every number from the facts.

6. Run the check until it passes:

   Copy

   python unit14/story_pack.py check --facts unit14/my_story/solution.json

7. Create unit14/my_story/talk.md with the CIO version as you would say it in two minutes: headline, one sentence about the picture, three numbers, the risks and owners, the ask.

8. Save your work:

   Copy

   git add unit14/story_pack.py unit14/story/ unit14/my_story/
   git commit -m "Unit 14: facts file, five audience briefs and a two-minute CIO talk"

Done when check --facts unit14/my_story/solution.json ends with Result: 5 briefs, 0 failure(s), both rewritten headlines are in your own words, and talk.md ends with the ask. Keep the folder: the capstone at the end of Unit 14 presents its result to these five audiences.

#Check yourself