Writing Wrappers Around Vendor Models

The FDE is the institutional memory of the engagement, responsible for continuity across change.

Programming

A System Two Years Into Its Life

Imagine an engagement that has been running for two years. The people on the customer side who first asked for the system have moved to other projects. The vendor has since swapped the underlying model for a newer one. A new FDE has been brought in to keep the system running. What does that person have to work with?

This article follows the answer the source gives to that question. It also covers what the source asks the current FDE to do now, while the engagement is still active, so that the answer is good when the successor arrives.

What do you think happens?

In the two-year scenario, where do you think the knowledge needed to keep the system running is held: in the former customer staff, in the vendor model, or somewhere else?

In the former customer staff
In the vendor model
In the wrapper and the FDE role that carries it

Reveal answer

Answer:

The source places the continuity role with the FDE, and carries that role out through the wrapper, which is the artifact that survives both changes.

The source does not say the FDE personally remembers every detail, and it does not say the customer's staff or the vendor's model keep the knowledge. The continuity is held by the wrapper, through which the FDE role operates.

Tracing Two Forces Over Time

Walk through the scenario in order and track two things at each step: who or what changed, and what the engagement still depends on. The source names two forces that act on an engagement over time. The first is on the customer side, where the team that works with the system rotates. The second is on the vendor side, where the model the system is built on gets replaced.

Neither change is treated as an exception or a failure. Both are treated as expected conditions of the production phase. An engagement is therefore expected to keep working through them, rather than only working while its original people and its original model remain in place.

In what order do the team rotation and the model change happen, and where does the wrapper carry continuity through each one?

The scenario in the source lists the team rotation first and the model swap after it, and then the new FDE arrives. The wrapper is the one element present across all of these points. The diagram is there to show where continuity is held, not to claim a fixed order for the two changes.

The FDE as Institutional Memory

Definition

Institutional memory of the engagement: the FDE's responsibility for continuity across change. The source states that the FDE is the institutional memory of the engagement.

Notice what this claim does and does not say. It does not say the FDE personally remembers every detail of the engagement. It does not say the customer's staff or the vendor's model keep the knowledge. Instead, it places the continuity role with the FDE and then names the artifact through which that role is carried out.

Key point

The FDE holds the role of continuity. The wrapper is the artifact that carries that continuity. A well-designed and well-documented wrapper is what survives both the team rotation and the model replacement.

Where the Wrapper Sits

The wrapper is the layer that stands between the application and the vendor model. The application code does not need to depend directly on the model; it depends on the wrapper. The diagram below shows this layering and the people who build and document it.

What sits between our application code and the vendor model, and what does each layer own?

In the source's picture, the two changing forces point at the wrapper rather than at the knowledge in anyone's head. The original FDE builds the wrapper, the customer team and the vendor model both change around it, and the replacement FDE receives the wrapper. The point of the picture is where the arrows end: the wrapper is the place the engagement's continuity is held.

Surviving a Model Replacement

When the vendor swaps the underlying model, the calling code should not have to change. The wrapper is where the replacement is absorbed. The diagram below compares the arrangement before and after a model swap.

When the vendor model is swapped, what changes inside the wrapper and what stays the same for the calling code?

In the after state, the model underneath has changed, while the application's view of the wrapper has not. The change is contained within the wrapper's layer. This is the reason the source treats the wrapper as the artifact that survives a model replacement.

Tracing a Handoff to the Successor

Worked example

Following the handoff in the two-year engagement

The original customer team has rotated away, the vendor has replaced the model, and a new FDE must keep the system running. What does the new FDE have to work with, and what did the current FDE need to do earlier?

1
Identify what changed
Two things changed: the customer-side team rotated, and the vendor-side model was replaced. Both are expected conditions of the production phase, according to the source.
2
Identify what the engagement still depends on
The engagement depends on continuity. The source places that continuity role with the FDE, and the wrapper is the artifact through which the role is carried out.
3
Check where the knowledge lives
The knowledge the new FDE needs should be in the wrapper and its documentation, because the source says the wrapper is what survives both changes. Knowledge that exists only in the former team's heads does not survive the rotation.
4
Decide what the current FDE must do now
The source asks the current FDE to write the wrapper as if writing for the FDE who will replace them, and notes that this successor is already on the way. The planning therefore cannot wait until handoff.

Result

The new FDE works from the wrapper and its documentation. Because the current FDE wrote for a capable newcomer with no context, the continuity survives both the team rotation and the model replacement.

Writing for the Successor

The source gives one concrete instruction for the production phase: write the wrapper as if you are writing for the FDE who will replace you. The instruction changes the audience you imagine while you work. Instead of writing for the person who understands the engagement today, you write for a capable newcomer who has none of your context.

Question	Writing for yourself	Writing for a future maintainer
Who is the imagined reader?	A builder who already has the context	A capable newcomer with none of your context
What can be left unsaid?	Anything you already know	Nothing that the successor would need to rebuild the context
Where does the context live?	In your own head	In the wrapper and its documentation
When is the work done?	Whenever you get to it	During the active engagement, before the successor arrives

How the audience changes the way a wrapper is built and documented. The comparison follows the source's instruction; it does not prescribe specific naming or structure beyond what the source states.

The source notes that the successor is coming, which means the planning for that successor cannot be postponed. The documentation and design of the wrapper are part of the current FDE's work during the active engagement, not a task reserved for the end.

Mistakes That Break Continuity

Common mistake
Treating the team rotation or the model replacement as an exception
Why it fails
The source treats both changes as expected conditions of the production phase, not as failures.
Do this instead
Design the engagement so it keeps working through both kinds of change.
Common mistake
Keeping the context only in your own head
Why it fails
The context you hold does not transfer to a successor unless it is in the wrapper and its documentation. The source places the surviving artifact in the wrapper.
Do this instead
Write the design and the context into the wrapper and its documentation while you work.
Common mistake
Writing for the person who understands the engagement today
Why it fails
The source asks you to write for the FDE who will replace you, a capable newcomer without your context.
Do this instead
Imagine a newcomer reading the wrapper cold, and document what they would need to know.
Common mistake
Postponing the documentation until handoff
Why it fails
The successor is already on the way, so the planning cannot be postponed.
Do this instead
Treat the wrapper's design and documentation as active work during the engagement.

Checking the Continuity of a Wrapper

MEDIUM

An engagement's customer team has rotated, and the vendor has replaced its model. A new FDE is about to take over. Describe, in your own words, what the new FDE should find in the wrapper and its documentation, and explain why the knowledge should not depend on the former team's memory.

Hints

Recall which artifact the source says survives both the team rotation and the model replacement.
Think about what the successor would need in order to work without your context.
Consider where the continuity role is placed in the source: the FDE, carried out through the wrapper.

Your attempt (not saved)

EASY

Pick one design decision you would make in a wrapper that calls a vendor model. Write one sentence explaining how a newcomer reading the wrapper cold would understand that decision without asking you.