Nobody Could Explain the System, Including Us

The gap in our own building

Every other case study in this series is about a gap in the market. This one is about a gap in us, and it is the one whose resolution made the rest of them writable.

As of mid-August 2026, this product had:

• no specification describing the system as a whole,
• no repository README worth the name — the admin console’s was literally zero bytes,
• an API reference documenting 44 paths of a surface that the customer application alone calls 119 unique paths of,
• design decisions surviving only in uncommitted working-tree files on somebody’s laptop,
• and no public product documentation at all.

That middle number is the one to sit with. Roughly eighty-nine endpoints the product depends on were undocumented — including the entire integrations surface, all workspace management, every performance endpoint, filters, bookmarks and notifications. Not deprecated endpoints. Load-bearing ones, called daily, in production.

This is the normal state of a product that has been shipping quickly. It is not a scandal. It is a compounding cost that nobody puts on a roadmap because it never causes a visible outage.

What it actually costs

Undocumented systems do not fail loudly. They fail as friction, distributed across everyone.

Onboarding takes weeks longer, and the tax is paid by the most senior person available, because they are the only one who knows. Features get built twice. Behaviour that was a deliberate decision becomes indistinguishable from behaviour that is an accident, so nobody dares change either.

And the failure mode we actually hit, which is the one worth publishing: a new coaching column was invented beside an old, empty, already-plumbed one — apparently without anyone knowing the old one was there.

Nothing broke. That is the point. The system absorbed a duplicated concept silently, and the only cost was a slow one.

What we changed: two documentation systems where there were none

1. A public documentation site

Fourteen pages at docs.theheartbeat.ai, organised for the reader rather than for the codebase:

Section	Pages
Start Here	Overview · Getting started · Connect your call data
Working with Calls	Dashboard · Call analysis
Reporting	Analytics · Agent performance · Weekly & monthly PDF reports
Administration	Workspaces & configuration · Users, roles & access · Account, usage & billing
Platform	Security & data handling · API & webhooks · Troubleshooting · Glossary

The thing we would point at is not the coverage but the register: it explains why, not just what. Three lines that would not exist in a reference-only document:

• “A call that is negative overall but positive on the agent’s side is usually a legitimately upset customer being handled well.”
• “High cross-talk on negative calls is one of the most reliable escalation signals in the platform.”
• “Missing features typically indicate permission restrictions rather than bugs.”

And it documents the boundaries rather than the highlights: masking is not retroactive, the audio itself is unchanged, retention is fifteen days, no HIPAA or PCI certification. Those are the paragraphs a buyer’s compliance team reads first, and they are the ones most vendors leave out.

2. A reverse-engineered internal specification

Thirty-six documents, a little over seven thousand lines: product, personas, features, architecture, data model, API surface, the ML pipeline, the scoring model, reporting, coaching, per-repository guides, a security register and a test plan.

The size is not the interesting part. The method is, because a reverse-engineered specification is a document that can very easily be confidently wrong.

Observed versus inferred is marked explicitly. Every claim is labelled as something read out of the code or something concluded from it. Those are different epistemic states and a document that blurs them is unusable for exactly the decisions it is meant to support.

Dead code is called out as dead, not described as a feature:

A reverse-engineered spec that documents dead code as intent is worse than no spec.

This is the failure mode of the genre. Read a codebase, find a half-built integration, describe it in the present tense, and you have created a feature that does not exist and that somebody will later build a plan around.

It names its own uncertainty in a dedicated gaps-and-questions document:

A reverse-engineered spec that hides its uncertainty is worse than one that names it.

It retracts its own errors in place, with the correction and the reason recorded. Two are on the record. A document that silently fixes itself teaches you not to trust any version of it, including the current one.

No secret values appear anywhere in it — only variable names and the locations of exposures. Which is what makes the folder safe to commit, and therefore safe to keep current.

Why we are publishing this one

Two reasons, and the second is the honest one.

For a buyer, documentation of this standard is a procurement asset. “We can answer that” and “here is the page” are different levels of vendor maturity, and the second one is checkable before you sign anything.

For us, publishing the before state is a commitment device. Having written down that the admin console’s README was zero bytes, we cannot quietly let it go back to that. A case study about your own engineering practice is only worth anything if it includes the state you were in.

What we do not claim

We do not claim the documentation is complete. It has a gaps document, that document is not empty, and it names real open questions — including a taxonomy reconciliation we have not finished and a per-workspace setting that is documented but not yet honoured downstream.

We do not claim the specification is authoritative over the code. It was derived from the code, which means where they disagree, the code is right and the document has a bug. That is stated in the document itself.

We do not claim this is unusual work. It is ordinary work that most teams postpone indefinitely. The only thing worth noting is that we did it, and that we wrote down which parts we were unsure about.

Where to start

If you are evaluating vendors, ask for their documentation before the demo rather than after it. Read a page about something that is hard — permissions, retention, a limitation — and see whether it explains or reassures.

If you are on the other side of this, running a product with no specification: the highest-value hour is not writing the architecture overview. It is writing the gaps-and-questions document, because that one tells you what the rest of the work is.

Book a demo and we will walk you through the documentation alongside the product it describes.

---

Related: Software That Needs a Team You Do Not Have on the operating model this documented, and The 5% Illusion for where the series starts.