Use Case Guide

Project handover pack: what a freelance data engineer hands back

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The handover is the part of a freelance engagement that decides whether the client calls you again or quietly writes the project off as risky. It is also the part that gets done in the last three days, from memory, under time pressure. Most of it can be produced from the repository you already have read access to, which is the argument for starting it in the first week instead.

Try it free
6 min readFor freelance data engineers closing an engagement

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

175/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The pack, item by item

A handover pack that holds up has a predictable shape: the repository with an updated README, an architecture diagram, deployment and run instructions, the inventory of third-party accounts and where their credentials live, the ticket history, and a closing note saying where each of those things is. Nothing on that list is surprising, which is exactly why leaving one out is noticed.

The diagram is the item clients quote back to you months later, because it is the only one a non-engineer can read. It is also the one most likely to have been drawn once at the start of the contract and never corrected, which turns your best artefact into your least accurate one.

Write the closing note last and make it short. The in-house engineer who inherits the project reads one page before they read anything else, and that page should be a map to the other items rather than a summary of the work.

Build it from the repository you already have

You already have read access to the code, which is the expensive part of documentation. Connect the repository at the branch or tag you are delivering and the sync produces both halves of the technical documentation: the diagram and a written architecture document generated from the same reading of the files. That is a starting draft with the real service and table names in it rather than a blank page on your last Friday.

Datadef reads GitHub, GitLab, and Azure DevOps. Public repositories need no token; private ones take a read-only token scoped narrowly, which is a much easier thing to ask a client security team for than write access. On a Terraform repository, the parser reads the .tf files directly, without running init, without touching state, and without any cloud credentials, so the infrastructure half of the pack can be produced from the same read-only grant.

What comes out of that parse is curated rather than exhaustive, which is worth explaining to the successor rather than letting them discover it. Repeated minor resources roll up into one node carrying the count and the member names, an overflowing module tail becomes a single supporting-resources node, and the resources that are wiring rather than architecture, role assignments, key vault secrets, group memberships, never become boxes at all. Nothing is dropped: the full inventory lands in the module reference table of the generated architecture document, which is the half of the pack the in-house engineer will actually search.

Correct the draft rather than accepting it. You know which of those tables are dead, which job is scheduled but disabled, and which service exists only because of a deadline in March. That knowledge is the actual deliverable, and it is worth putting on the canvas as annotations while you still remember it.

Hand over the living version, not a screenshot

Put the diagram in the repository README with one markdown image line. From that point the picture in the README is the current diagram rather than an export from handover week, and the in-house team gets a correct picture on the day they finally open the repo properly.

The client keeps reading rights without needing anything from you: a view-only link opens with no sign-in. If they want to keep editing the diagram after you leave, that is where a plan on their side comes in, because editing requires an active plan on both sides and the server enforces it, whatever role the share dialog was given. Say this in the closing note so it is not discovered three months later.

When you are done, unlink the repository. The project keeps its content and stops reading their code, which is the correct end state for a contract that has ended.

# Data platform

![Architecture](https://datadef.io/api/embed/your-project-slug)

Handover notes: see docs/handover.md
Owner from 2026-09-01: the in-house data team

Start the pack at kickoff, not in the last week

Handover documentation assembled at the end is documentation written from memory, and memory is worst about exactly the things a successor needs: the workaround, the manual step, the reason a job runs at an odd hour. Connect the repository in the first week and let the diagram exist for the whole engagement.

Running it that way turns handover into a review instead of a writing sprint. The sync re-reads the branch about once a day, commits that change nothing structural leave the diagram alone, and any node you positioned by hand keeps its place, so the picture you have been showing at every checkpoint is the picture you hand over.

It also gives you something to show at checkpoints, which tends to be worth more in a freelance engagement than the handover itself.

FAQ

What belongs in a freelance handover pack?

The repository with an updated README, an architecture diagram, deployment and run instructions, the list of third-party accounts and where their credentials live, the ticket and requirements history, and a short closing note that says where each item is. The closing note should be a map to the other items, not a summary of the work.

Can I generate the handover documentation from the client repository?

Yes, if you have read access. A read-only connection to GitHub, GitLab, or Azure DevOps at a branch or tag produces a diagram and a written architecture document from the files it reads. Treat it as a draft and add the things only you know, such as which jobs are disabled and which components are temporary.

Does the client need a paid plan to keep the diagram after I leave?

Not to read it. Viewing is possible through a view-only link with no sign-in, and viewers can see the diagram and its versions. Editing is what needs an active plan on both sides, which the server enforces, so say so in the closing note rather than letting them find out later.

What happens to my access when the contract ends?

Unlink the repository. The project keeps its content and stops reading the client code, which is the correct end state once the engagement is over. Nothing about the diagram depends on the connection staying alive, so the client keeps the documentation and you stop holding a read token on their repository, without either side having to delete anything.

Does connecting a Terraform repository need cloud credentials?

No. The .tf files are parsed directly from the repository. There is no init, no plan, no state access, and no cloud credentials involved, which makes it a much easier request to put in front of a client security team than anything requiring provider access.