Documenting Probabilistic Systems

Sift API

Demonstration piece. Shipped client documentation is under NDA, so this was built to the same standard instead.

Three documents, three registers: teaching, reasoning, contract.

Problem: An API that returns confidence scores instead of answers, documented as though it returned answers.
Insight: An extraction API can be confidently wrong, and the response body looks the same either way. Documentation that only explains the happy path leaves the reader to discover this in production.
Result: Tutorial-first documentation that shows a wrong answer in step 3, before the reader has written anything that depends on the right one.

The full story

Extraction APIs return a value and a number between 0 and 1. Most documentation for them explains the number in a short note near the end, after the reader has already been taught to treat the value as the answer. By then the integration has been designed around the happy path, and the confidence score is a field somebody handles later.

This set inverts that order. The quickstart sends two documents: a clean invoice that works, and a photographed receipt that comes back with the total misread and status still set to succeeded. The wrong answer is step 3 of the tutorial, not an appendix, because the reader has to meet it while they are still deciding how to build.

The second document does the work the usual confidence-score table cannot. A table of thresholds tells a reader what a number means; it does not tell them what to do. The explanation replaces the question "how confident is the model" with "what does this field cost when it is wrong", which is the question that actually produces a routing decision, and it ends with a per-field threshold table an operations team can argue with.

Key decisions

Show the failure inside the tutorial rather than in a note. An honest quickstart is slower to read and produces integrations that survive contact with real documents.
Give confidence a definition that can be checked: across a batch of fields scoring 0.80, about 80% are correct. A vague definition invites the reader to substitute their own, and the one they substitute is always more optimistic.
Separate the three failures that look identical in the response body: a bad document, a wrong extraction, and a wrong request. They arrive as the same low number and they need completely different responses, and a team that cannot tell them apart never improves.

What it taught me

Putting the wrong answer in the tutorial made the quickstart slower and slightly less impressive, and I went back and forth on it. What settled it was imagining the support thread six months later, from a team that had built a straight-through payment flow on top of a field that is right about 60% of the time on photographed receipts. They would not have been wrong to read the original tutorial that way.