What handover documentation should actually contain

When a build is handed over, you should get five short documents: an architecture note, a named owner and backup, a record of credentials and connections with their expiry dates, a failure playbook, and step-by-step instructions for the three changes you are most likely to need. Most handover documentation is a screenshot tour that goes stale in a month. These five are worth having, and they are all short.

This applies to any Power Platform or SharePoint build: a set of Power Automate flows, a Power App, a Copilot Studio agent or an intranet. It is written for the person who will be holding the system after the supplier leaves, usually an ops lead, an IT generalist or a finance systems person who did not build it.

1. The architecture note

One page. What connects to what, where the data lives, which accounts and connections it runs under. A diagram is fine. This is the document that matters at 6am when something breaks.

A good architecture note answers, at a glance:

• Which environment the solution lives in, and the name of the solution
• Every app, flow, agent and list in it, with a one-line purpose each
• Where each piece of data is stored: which SharePoint site and list, which Dataverse tables
• What it talks to outside Microsoft 365, such as an ERP, payroll or a job management system
• Which connections and accounts it runs under

If the system is simple, this is half a page. If the note runs to ten pages, the system is probably more complicated than it needs to be, and that is worth knowing too.

2. The owner

A name, and a named backup. Not a team. Not an inbox.

The owner decides on change requests, is the first call when something looks wrong, and keeps the other four documents current. The backup covers leave. Write both names at the top of the architecture note so nobody has to go looking.

3. Credentials and connections

Which service accounts run the flows, where the secrets are stored, and when they expire. An enormous number of automations fail because a connection was authenticated by someone who has since left.

A simple register is enough:

The column people leave out is the last one. Client secrets and certificates have expiry dates. Put each one in a shared calendar with a reminder a month ahead, assigned to the owner. If any connection runs as a named person rather than a service account, it should be flagged here as something to fix; our note on who owns the build explains why.

4. The failure playbook

For each flow: what does failure look like, who is notified, and what are the first two things to check. Most failures are the same handful of causes — an expired connection, a permission change, a renamed column.

That pattern makes a short playbook genuinely useful. Write it as a decision path rather than prose:

For anything that does not fit those three, the playbook should say who to call next, whether that is your IT provider, the original builder under a support arrangement, or an internal person.

It also helps to know what "failure" looks like for each flow. Some fail loudly with an error. Others fail quietly: the flow runs but does nothing because a filter no longer matches. A line per flow saying "if this stops, you will notice because..." saves hours.

5. How to make the three most likely changes

Not everything. The three changes that will actually be requested — add an approver, change a threshold, add a field to the form. Written as steps someone competent can follow.

Each one should name the exact place to make the change and what to test afterwards. As an illustrative example, for a purchase approval flow:

1. Add an approver. Open the approval matrix list on the Finance site, add a row with the cost centre and the approver's email, and submit a test request under that cost centre.
2. Change the approval threshold. Edit the threshold value in the settings list (not inside the flow), then submit one request just under and one just over the new value.
3. Add a field to the form. Add the column to the list, add it to the app's form screen, publish the app, and check the new field appears in the approval email.

Notice what makes these easy: thresholds and approvers live in lists, not hard-coded inside flows. If your handover cannot describe changes this simply, ask why the values were built into the logic.

What you do not need

A full manual of every screen. Nobody reads it, and it is wrong within two releases.

You also do not need a document per flow restating what the flow designer already shows. Power Automate and Power Apps are reasonably readable to a competent person once they know where to look; the architecture note tells them where. Spend the effort on the things the tools do not show you: why decisions were made, what expires, and what to do when something breaks.

Keeping it current

Documentation that is accurate on handover day and never touched again is only useful for a few months. Two habits keep it alive without much effort. First, a short change log at the bottom of the architecture note: date, what changed, who changed it. Second, a quarterly fifteen-minute review by the owner, checking the connection register against upcoming expiry dates and confirming the backup person is still in the business. Neither needs a tool; a SharePoint page and a recurring calendar reminder are enough.

Where it should live

In your tenant, next to the system. A page or document library on the SharePoint site the solution belongs to works well, with the solution export files stored alongside it. Not in the supplier's portal, not in an email attachment, not in someone's OneDrive.

The handover checklist

The test

Hand the documentation to someone who did not build it. Ask them to add an approver to a flow. If they cannot do it in fifteen minutes, the handover is incomplete — regardless of how many pages it runs to.

Run the test before the final invoice is paid, with the supplier still available to fix the gaps. It takes less than an hour and tells you more than any review meeting.

What to do next

If you are about to start a build, ask what handover includes before you sign. The answer tells you what happens after they are paid. If you already have systems running that nobody fully understands, start with the connection register: list every flow, what it runs as and when its credentials expire. That one page prevents the most common failures. If you would like a second pair of eyes on what you have, the free diagnostic audit covers exactly this.