Skip to content

PATTERN Cited by 1 source

Business to Engineering Requirement Translation

Problem

Business-voice requirements (from accountants, lawyers, product managers, compliance officers, business analysts) are often:

  • Dense with domain vocabulary that doesn't map to engineering concepts without explicit translation.
  • Ambiguous at the edges — unstated assumptions about edge cases, tie-breaks, numeric precision, temporal boundaries.
  • Underspecified on purpose — describing what without why, leaving engineers to guess the underlying intent.
  • Unreviewable by engineering — engineers can't validate a requirement they don't fully understand; reviews become rubber-stamps or arguments about the wrong thing.

When engineering writes a pipeline from this kind of requirement unchanged, the result is pipelines that accountants / lawyers / PMs can't validate + engineers can't defend, because there's no shared contract about what the code should do.

Pattern

Before implementation, formalise a three-step translation from business-voice to engineering-voice:

Step 1: Glossary Dictionary

Build an explicit table mapping business terms to the company's specific engineering concepts. Each entry pins down a single meaning; after this step, every stakeholder uses the same word to mean the same thing.

Business term Engineering term
(business vocabulary term) (the specific engineering object / field / service that term maps to)

Step 2: Purpose + Example Calculation

For each load-bearing requirement, write:

  • Purpose — 1-2 sentences explaining why the requirement exists. Keeps engineers grounded in intent when they hit edge cases.
  • Example Calculation — a concrete worked example with specific numbers showing exactly what the rule produces. Removes all ambiguity about how the rule applies to real inputs.

Step 3: Engineering Rewording

Restate the requirement in engineering-voice — in language that pipeline code + review can validate against. The engineering rewording should be:

  • Pipeline-code-actionable (names specific events, fields, operations).
  • Reviewable by both engineering and the business stakeholder.
  • Grounded in the Glossary Dictionary vocabulary.

Yelp's canonical worked example

From the 2025-02-19 Revenue Data Pipeline post (full details at concepts/glossary-dictionary-requirement-translation):

Original (accountant-voice):

"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 maps 5 terms: Revenue Contract → subscription order; Booking → purchase completion; Fair Value → standalone price; Each Line → fulfillment-billing granularity; Invoice Amount → on-ledger net amount.

Purpose + Example: revenue allocation uses standalone price, not billed amount. Worked example: Product A $100 + B $20 standalone, bundled at $100 total → A books $83.33, B books $16.67.

Engineering rewording (engineer-voice):

"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 directly actionable: "on booking event, send gross amount, allow it to differ from billed."

Composes with

  • concepts/data-gap-analysis — the next step after requirement translation. The engineering rewording tells you what to build; data gap analysis tells you what data you have vs need.

Together, glossary + purpose + example + engineering rewording + data gap analysis form the scoping workflow for any cross-functional pipeline project.

When to use

  • Financial / regulatory / compliance pipelines — where the source of requirements is an accounting / legal / compliance team with specialised vocabulary.
  • ML feature engineering — where product managers describe "engagement" or "churn risk" in ways that need operational definitions.
  • Cross-functional API design — where the consumer speaks a different technical dialect than the producer.
  • Large-scope migrations — where the "before" and "after" vocabularies differ.

When not to use

  • Pure technical requirements — when both sides speak engineering, the ceremony doesn't earn back its cost.
  • Small-scope bug fixes — overkill.
  • Prototype / exploratory work — when requirements are explicitly flexible and will be re-scoped after the prototype exposes real constraints.

Seen in

Last updated · 476 distilled / 1,218 read