Knowledge Transfer as a Habit

Context

When I moved on from Sky, the team was going to inherit the low-code workflow platform whose UI I’d led (Building a Low-Code BPMN Workflow Platform). My job in the final stretch was to make sure everything they needed was written down, explained and easy to pick up.

Problem

Any platform carries knowledge that’s easy to under-document: not the what, which is in the code, but the why. Without it, the easiest path for the next developer would be to bypass the model and add bespoke code, which would undo the reuse the platform had been built for. The handover had to pass on the reasoning, not just the recipes.

What I did

I ran a series of structured knowledge-transfer sessions, each backed by written documentation the team could return to:

1. Diagram modelling and adding a property. The standard behind the editor; where constants and typed models live; the step-by-step recipe; and the one rule that matters most: always update through the model’s API, never mutate directly, or you lose undo/redo and change events.
2. Form building. How to choose a drag-and-drop form framework (anything whose layout is structured JSON can work), preferring ones that reuse our own components over fully custom builders.
3. The API gateway. Registering endpoints, swapping environments with configuration, throttling (Rolling Out an API Gateway).
4. Permissions. Route-level and feature-level checks, and why both the UI and the server must be audited and tested.
5. Performance. Every input change executes against the model, so debounce inputs and show saving state.
6. What next: a reuse strategy. Reusable form snippets, named sub-workflows for shared processing, and a feature catalogue of tested, approved pieces, so new use cases start from proven building blocks.

Alongside the sessions I tidied the backlog so the next priorities were clear and ready to pick up.

Outcome

The team took over with documented processes, recorded sessions, a clear reuse strategy and a backlog they could keep working through. The recipes meant the most common change, adding a new configurable property, no longer needed me.

What I’d do again

• Pair every session with a document. Talks are forgotten; documents get re-read the first time someone actually needs them.
• Teach the “why” alongside the “how”. The rule about updating through the model sticks only if people know what breaks when they don’t.
• End with direction, not just description. A reuse strategy gave the team somewhere to go, not just a map of where they were.

What I’d do differently

Make it continuous from day one. The best knowledge transfer happens all the time: documentation written as features ship, pairing on every new area, decisions captured in Architecture Decision Records. Then a handover is a summary of what’s already written down.

Related notes

Pair Programming · Design Review Readiness Checklist · Communicating with Stakeholders