Skip to content

CONCEPT Cited by 1 source

Glossary Dictionary Requirement Translation

Definition

Glossary Dictionary Requirement Translation is a three-step methodology for converting ambiguous non-engineering requirements (accountant-voice, legal-voice, product-voice, business-analyst-voice) into engineering-consumable requirements that pipeline code can be written + validated against.

The three steps, from Yelp's 2025-02-19 Revenue Data Pipeline post:

  1. Glossary Dictionary — an explicit table mapping business terms to engineering terms in the target company's vocabulary. Aligns cross-functional understanding before any implementation begins.
  2. Purpose + Example Calculation — extract the why of the requirement and pair it with a concrete worked example that leaves no room for misinterpretation.
  3. Engineering Rewording — restate the requirement in language that pipeline code and review can validate against.

The Yelp worked example

Original accountant-voice requirement

"The total contract value (TCV) should be captured during booking as revenue to be recognized based on fair value allocation by each line will be different from invoice amount."

Glossary Dictionary

Business term Yelp-engineering term
Revenue Contract A subscription order placed on Yelp's Biz Site
Booking The moment when a user completes a subscription purchase request
Fair Value The gross amount if we sell this product standalone
Each Line The minimum granularity that we track fulfillment and billing of a product feature
Invoice Amount The net amount that on ledger for a product feature in a revenue period

Purpose + Example Calculation

"Make sure revenue allocation is based on the price if we sell this product alone, and not based on how much we actually bill this product."

  • Product A standalone selling price: $100
  • Product B standalone selling price: $20
  • Subscription bundle: A for $100, B as add-on for free.
  • Total Revenue of subscription order ($100) splits based on the standalone selling price:
    • A's share: 100/120 × 100 = $83.33
    • B's share: 20/120 × 100 = $16.67

Engineering Rewording

"The REVREC service requires a purchased product's gross amount to be sent over whenever a user completes a subscription order, this amount is possible to be different from the amount we actually bill the user."

This is pipeline-code-actionable: "send gross amount on booking event, allow it to differ from billed amount."

Why the original wording fails

The accountant-voice requirement packs four load-bearing concepts into one sentence — TCV, booking, fair-value allocation, invoice amount — each of which means something specific in accounting but something different (or nothing) in engineering. Without a Glossary Dictionary, every engineer interprets each term based on their own prior exposure. Three engineers reading the same sentence will write three different pipelines.

The Glossary Dictionary is the contract that pins down each term to a single meaning before implementation starts.

Why Purpose + Example matter

Natural-language requirements under-specify numeric edge cases. The Purpose + Example pair:

  • States the intent in business terms — "revenue allocation based on standalone price, not billed amount" — so engineers understand why the rule exists.
  • Shows the arithmetic — A: 100/120×100, B: 20/120×100 — so there's zero ambiguity about how the rule applies to real numbers.

This combination makes ambiguity impossible to hide. An accountant reviewing the example either accepts that the arithmetic captures their intent, or spots the gap and corrects it — before engineering writes the code.

Portability beyond revenue recognition

The methodology lifts cleanly out of the revenue-recognition domain. Any cross-functional handoff with ambiguous vocabulary benefits:

  • Legal-to-engineering — GDPR/CCPA compliance requirements ("data subject access request," "right to erasure," "lawful basis") have precise legal meanings that don't map to generic engineering vocabulary.
  • Product-to-engineering — product-manager requirements about "engagement," "active user," "conversion" rarely survive contact with instrumentation code without a Glossary Dictionary.
  • Security-to-engineering — threat-model requirements ("attacker-in-the-middle," "replay resistance," "forward secrecy") have precise cryptographic meanings.

The reusable pattern is patterns/business-to-engineering-requirement-translation.

When not to use

  • Ad-hoc bug reports — overkill for simple defect fixes.
  • Pure technical requirements — when both sides speak engineering vocabulary (e.g. infrastructure migration, library upgrade), the methodology adds ceremony without reducing ambiguity.
  • Extremely short turnaround — the full three-step methodology takes time; for a two-day prototype, a 10-minute whiteboard conversation may suffice. But when the pipeline is load-bearing (revenue-recognition, compliance, safety- critical), the investment pays back.

Seen in

Last updated · 476 distilled / 1,218 read