How should an agency document an accessibility remediation for a client audit trail?

Remediation work is only as defensible as its documentation. A clear record of what changed, why, and how it was tested turns a pile of closed tickets into an audit trail a client can rely on.

The fix is only half the work

When an agency finishes remediating a client's accessibility findings, the natural instinct is to move on. The tickets are closed, the rescan is green, the invoice goes out. But the work the client actually bought was not just the fixes. It was the ability to prove the fixes happened. A remediation nobody can reconstruct six months later is, for legal and business purposes, a remediation that barely happened.

Documentation is what converts labor into an asset. The scan history shows diligence. The remediation records show follow-through. Together they tell the story a demand letter, an acquirer, or a new in-house team will ask for: what was wrong, what did you do about it, and how do you know it worked.

One record per finding, not one per sprint

The most common documentation failure is batching. An agency fixes forty findings across a sprint and writes one summary: "addressed all high-priority issues." That sentence is useless as evidence. Nobody can tell which findings were fixed, which were waived, and which are still open under a different name.

Keep one record per finding. Each record lives from the moment the finding is reported until it is verified fixed or formally accepted as a known limitation. The record does not have to be long. It has to be complete: the finding, the fix, the test, the result. Forty thin records beat one thick paragraph every time.

What each remediation record should contain

A useful record has six parts. First, the finding itself: the rule violated, the page and component, and a screenshot or markup snippet showing the problem. Second, the agreed fix: what the developer planned to change, in plain language the client can follow. Third, the code reference: the theme file or commit that contains the change, so anyone can locate it later.

Fourth, the test: how the fix was verified, naming the method. A keyboard pass, a screen reader check, a contrast measurement. "Retested" is not a method. Fifth, the result: pass or fail, with the date. Sixth, the owner: who made the fix and who verified it. Two different people, ideally. The verifier should not be the person who wrote the change.

Before-and-after evidence beats assertions

For every meaningful fix, capture the before state and the after state in the same format. If the finding was a keyboard trap in the mobile menu, the record should show the trap (a screen recording is ideal) and then the fixed flow (another recording). If it was a contrast failure, show the measured ratio before and after.

This is the part agencies skip because it feels slow. It is slow. It is also the only part of the record that convinces a skeptical third party. A row in a spreadsheet that says "fixed" convinces nobody. A pair of recordings ten seconds long each ends the argument.

Tie every fix back to its success criterion

A fix is only done when it meets the criterion that defined the finding. If the finding was "the checkout error summary is not announced to screen readers," the success criterion is not "error summary added." It is "submitting the checkout form with errors moves focus to the summary and the screen reader announces it." Write the criterion down before the fix, then record whether the test met it.

This discipline also catches the near-miss fixes: changes that address the letter of the finding while missing the experience. A visible label added to a field but never programmatically associated with it will pass a visual check and fail a screen reader test. The criterion, written first, is what forces the real test.

Record waivers and known limitations honestly

Not every finding gets fixed. Some live in platform code the agency cannot change. Some the client deprioritizes. Those decisions are fine, but they must be recorded as decisions, not left as silent open tickets. A waiver record names the finding, the reason it is not being fixed, who accepted the risk, and the date the decision gets revisited.

Honest waivers protect everyone. The agency is not blamed later for a known issue. The client owns a conscious choice instead of an unpleasant surprise. And when the platform limitation is eventually lifted, the revisit date turns the waiver back into a work item instead of a forgotten footnote.

Close the record the same week you close the ticket

Documentation rots fast. A fix documented three months later is a reconstruction, not a record, and reconstructions are where details get invented. Make the record part of the definition of done: the ticket cannot close until the six parts are filled in and the evidence is attached.

The practical trick is to write the record as the work happens. The developer pastes the before screenshot when they pick up the ticket. They paste the commit link when they push. The verifier adds the test result when they test. Nobody sits down at the end of the month to write forty records from memory, because nobody can.

Keep the archive boring and consistent

The final property of a good remediation archive is that it is dull: same template, same naming, same location, month after month. Boring archives survive staff turnover. Clever ones die with the person who invented them.

Store the records where the client can reach them without asking you. A shared folder with one subfolder per month, files named by finding ID. When the client's new developer, their lawyer, or their acquirer's auditor asks for the accessibility history, the answer is a link, not a project. That link is the product the remediation work was always building toward.