Back to writing

Engineering practice · Long-form

The product bible

Ask three people whether the product supports a requirement and you get three answers. We stopped writing the catalogue and started deriving it from the code every week, with one export an AI can answer from without inventing a feature.

Published · November 2026~11 min read

1. Three answers to one question

"Do we support this?" is the most common question in an enterprise software company and the hardest to answer the same way twice. Sales says yes, because a version of it was demonstrated once. Product says it is on the roadmap, because the version that was demonstrated is not the version the customer means. Engineering says it depends, and is right, and is interrupted for twenty minutes to explain why. Multiply by a requirement list of four hundred lines and an RFP deadline, and the interruptions become a job.

Our HRMS has seventeen modules and several hundred screens, built over years by people who have since moved teams or companies. The catalogue that described it was a slide deck, a feature matrix in a spreadsheet, a documentation site, and the memories of a few long-serving engineers. Each was true on the day it was written. None was true on the day it was read, because the product had moved and the documents had not.

The fix was not to write a better catalogue. Written documentation drifts from the thing it describes the moment the next commit lands, and no amount of process makes engineers update a spreadsheet after a release. The fix was to stop writing it and derive it.

Documentation that is written drifts. Documentation that is derived can only be wrong the way the code is wrong.

2. Reading the code as it is

The generator reads three repositories the way a careful new engineer would on their first week, without asking anyone. The React application's screen folders say which screens exist and in which product area. The GraphQL schema files say which queries and mutations back them, and the doc comments on those operations are the only description many of them have. The database migrations that seed menu labels say what the customer calls each screen, which is often not what the folder calls it. Git history says when each screen last changed and which commits of the last fourteen days were features or fixes rather than noise.

The agentic layer gets the same treatment. The capability catalogue and the tool descriptions in the agent runtime are read directly, so the list of what the assistant can do is the list the assistant actually uses, not a marketing restatement of it. If an engineer adds a tool, it appears in the bible the following week without anyone writing it up.

Some things the code cannot say for itself: what is planned, which third-party systems are integrated, how we compare to named competitors, and which AI features are real in production versus demonstrable with caveats. Those live in files their owners already maintain, a roadmap page per module, an integrations register, two comparison workbooks, an internal evidence note, and the generator reads them from where they are rather than asking for a copy. The rule is that nobody maintains anything for the bible. The bible reads what people maintain anyway.

3. Seventeen modules, one catch-all

Source folders are not product modules. The folder tree reflects who built what in which year; the module list is how a buyer thinks. So the generator carries a mapping from folders to seventeen modules, from core HR and organisation through recruitment, onboarding, attendance and time, leave, payroll, compensation, travel and expense, performance and talent, workforce planning, learning, engagement, helpdesk, separation, analytics, workflow and platform, and conversational AI. Grouping rules within a module turn a flat list of screens into sub-modules by name.

The one rule that keeps the mapping honest: a source folder that is not mapped lands in the workflow and platform module, visibly, rather than being dropped. A missing screen is invisible and stays missing. A screen in the wrong place is noticed by the first person who reads that tab, and the fix is one line in the mapping and a rerun.

4. Two kinds of column

A derived catalogue has a weakness: the code knows what exists but not how to describe it to a buyer, whether it is generally available or a configuration option, or what the standard caveat is when a prospect asks. People know those things. So the workbook has two kinds of column, distinguished by colour so nobody is confused about which is which.

Generated columns are rebuilt from code on every run and overwritten without mercy. Editing one is wasted effort and the header says so. Curated columns are matched by a stable identifier and survive every rebuild: a customer-facing description written the way an RFP answer reads; an availability chip, generally available, configuration, beta, client-specific or deprecated; a deep link to the how-to page; RFP notes with the standard wording or the standard caveat; an owner; and a hide flag for the demo screens and half-finished experiments that should not appear in a catalogue a customer might see.

The practical advice is to curate in RFP order. The generated description of a feature is its name and its operation counts, which is enough to prove it exists and not enough to sell it. Start with the fifty features that come up in every questionnaire, and let the long tail stay thin until someone asks.

The product bible · derived from the code every week, curated by people, read by AI

Source · code

Three repositories, read as they are

React screen folders, GraphQL schema files with their doc comments, menu labels seeded by migrations, the agent capability catalogue and tool descriptions, git history for last-changed dates and the last fourteen days of commits.

Source · files

What the code cannot say

Roadmap pages, the integrations registry, the competitor comparison workbooks and the internal AI evidence notes. Each lives where its owner already edits it.

Source · people

Curated columns

Customer-facing description, availability (GA, configuration, beta, client-specific, deprecated), how-to link, RFP notes, owner, hide. Matched by stable id, so they survive every rebuild.

Generator

Pull production branches, rebuild every generated column, keep every curated value, write four outputs

Seventeen product modules mapped from source folders. Anything unmapped lands in a visible catch-all so it is noticed, not lost. Generated columns are overwritten on purpose; curated ones never are.

Workbook

The source of truth

One sheet per area. The only place curated columns are edited.

Viewer

Offline, read-only, tabbed

Modules and features, agents, embedded AI, roadmap, integrations, competition, what changed, API surface, and a question box.

JSON

For tools

The same content as structured data for anything that wants to consume it.

AI export

Compact text plus answering rules

Uploaded with a requirement list. Six allowed verdicts; never claim what is not listed; a bare screen name means 'needs product confirmation'.

The how-to documentation stays where it is. The bible says what exists and where. When the two disagree, one of them is wrong in a way you can now see.

5. One content, four outputs

A weekly run pulls the production branches, rebuilds every generated column, keeps every curated value, and writes four things from the same content. The workbook, one sheet per area, is the source of truth and the only place curated columns are edited. A read-only HTML viewer opens offline in any browser, with tabs for modules and features, the agents, embedded AI, roadmap, integrations, competition, what changed in the last fortnight, the full API surface, and a question box. A JSON file carries the same content for any tool that wants it. And a compact markdown export exists for one purpose: to be uploaded to an AI assistant alongside a requirement list.

Four outputs sounds like three too many until you watch who opens which. Product and presales live in the workbook. Implementation consultants open the viewer on a client site with no network. Engineering reads the JSON into other tools. The RFP team never opens any of them and uploads the export.

6. Teaching the AI to say no

The export is the part I would keep if I had to throw away the rest. It is the product described in a few hundred kilobytes of plain text, and at the top of it are the rules for answering. For each requirement the assistant must reply with a verdict from a closed list: available as standard, available with configuration, partially available, on roadmap, not available, or needs product confirmation. Then how: the module, sub-module and feature that cover it and the configuration needed. Then the gaps, with the roadmap item and its status if one exists. Then the feature identifiers it relied on, and a pointer to the documentation site for the how-to.

Two rules do most of the work. The first: never claim a capability that is not listed. The second: if the only evidence for a feature is a screen name or a service name with no curated description, answer "needs product confirmation" rather than guessing what the screen does. AI items tagged as emerging are to be described as not generally available; AI that runs in a separate service is to be described as such. The assistant is being asked to be a careful presales engineer, and a careful presales engineer says "I will confirm" more often than "yes".

This inverts the usual worry about language models in presales. The risk was never that the model would not know the product. Fed the export, it knows the product better than any single person. The risk is that it answers like a salesperson, and the cure is a verdict list that makes "I do not know" a legitimate, expected, first-class answer. The rules are a close cousin of the ones in What we let the HR assistant answer, and what we don't: the scope of what the assistant may say is decided before the first question, not after the first mistake.

The model does not need to know more. It needs permission to know less.

7. What the bible is not

It is not the how-to documentation. The documentation site explains how to configure a leave policy; the bible says that leave policies exist, in which module, backed by which operations, with a link to the page that explains how. The two answer different questions and the discipline is to keep them from answering each other's.

It is not the engineering checklist. The list of what every enterprise system must have, and where ours stands against it, is a different document with a different audience, and it is deliberately excluded from the bible, for the reasons in Enterprise-grade is a list. A catalogue of what exists can travel to a customer. An assessment of gaps cannot.

And it is not customer material as generated. The internal evidence notes and demo caveats are in the workbook because the implementation team needs them, and they stay inside. For a customer, the curated descriptions are copied out; the evidence columns are not. The hide flag exists for the same reason.

8. The operating rule

The run is scheduled weekly and takes minutes. Rebuilding only the viewer and the export after someone edits a curated column, without re-reading the code, takes seconds. The operating rule that makes it stick is a single sentence: when the bible is wrong, either the code is wrong or a curated column is wrong, and fixing whichever it is fixes the bible next week.

That sentence changes conversations. A feature that is "definitely there" but absent from the bible is a feature that was never merged, or was merged into a folder nobody mapped, and either way the question has become answerable. A description that reads like a slide rather than a capability gets rewritten by the owner named in the row. A roadmap item that has been "next quarter" for three refreshes is visible as such, in a tab the sales team opens.

The pattern generalises beyond a product catalogue. Anything a company keeps a written register of, and keeps getting wrong, is a candidate for derivation: the API surface, the integrations, the tools an agent may call. It is the same move as the one in Two migrations, where the React shell asks the backend which screens a tenant has rather than carrying a copy of the answer. Ask the system. Do not maintain a description of it.

9. The honest part

The generated descriptions are thin, and they stay thin for every feature nobody has curated. A name and two counts tell a reader the feature exists; they do not tell a buyer what it does. The bible is only as persuasive as its curated rows, and curation is still human work that competes with everything else.

Demo screens, prototypes and abandoned experiments appear in the catalogue the moment they are in the repository, because the generator cannot tell a demo from a product. The hide flag handles it, after someone notices. The first few runs are mostly noticing.

And derivation is not truth. A screen that exists and does not work is listed as a screen that exists. A GraphQL operation with a wrong doc comment is described wrongly with perfect confidence. The bible removes one class of error, the drift between description and code, and leaves the class underneath it untouched. Which is the point of the method and also its limit: the catalogue is now exactly as right as the product, and no righter.

Do not describe the system. Ask it, and write down the rules for the answer.

The checklist that lives beside this catalogue and is kept out of it is in Enterprise-grade is a list; the guard rails that taught us to give an assistant permission to decline are in What we let the HR assistant answer, and what we don't; and the platform whose screens the generator reads is described in Two migrations.

Drowning in requirement lists, or tired of being the person who knows whether the product does the thing? Let's talk.

More writing