For programs

Every written chapter has a report beside its reading page. The report is generated from the chapter's data files and its findings text, and nothing in it is written separately, so it is the form of a chapter that a program should read. The reading page, the essay where a chapter has one, draws the same numbers from the same files.

Where the report is

/<slug>/report is the report as HTML and /<slug>/report.md is the same report as Markdown, served as text/markdown. The chapter page and the report page each carry a <link rel="alternate" type="text/markdown"> that points at the Markdown, and the report's last section, #formats, links every machine copy of the chapter.

/llms.txt lists one line per written chapter: its label, its title, the URL of its Markdown report and its dek with the numbers filled in. /llms-full.txt is every report's Markdown in one file, in reading order. Both sit at the root of the book, under https://vishalsingh.org/decisionai.

Sections a program can link to

Each section of a report has a stable id: #identification, #principal-estimates, #findings, #tables, #estimates, #definitions, #methods, #limits, #references, #provenance and #formats. The principal estimates are the facts the dek and the opening of the findings cite, and they are the answer to quote first.

Inside a report, each figure's table is #table-<figure id>, and a figure with tabs has one table per panel at #table-<figure id>-<k>, counting panels from one. Each estimate's row is #fact-<fact id>, each reference is #ref-<reference id>, and each section of the methods is #methods-<section id>.

Table n of a report is figure n of the chapter's findings text, so "Table 3" in a report holds the rows behind the third figure of the findings. An essay numbers its own figures, and it names a report table by the report's number.

The Markdown report

The Markdown copy prints the same sections in the same order. Each number in the prose prints as on the page, followed by its interval where the page prints one; a figure becomes a line that names its table; a citation becomes a bracketed number that matches the reference list; a cross-reference becomes the chapter's number, title and absolute URL; a margin note follows its sentence in parentheses. A table prints its cells with the formatting the site uses, and a long table stops at a cap with a link to its JSON copy.

Machine copies of the data

/report/<slug>/facts.json is a byte-for-byte copy of the chapter's facts file, and /report/<slug>/figures/<id>.json is a copy of each figure file, with its title, subtitle, notes, source, specification and rows. A figure whose rows are too many to inline, such as the item-level answers behind an interactive scenario, keeps them in a payload file under /data/<slug>/; the figure file names the payload, and the report's table section names its path. A payload URL on the site carries a short content hash in its query, so a rebuilt file gets a new URL; the path without the query always returns the current file.

What a fact holds

A fact record carries a value and a display, the value as the prose prints it. Where they apply it also carries a unit, a population, a period, a source (a dataset id from the data sources page), an estimand, the weights, a ci (the interval as a pair of bounds) with its ciLevel, n (the number of units behind the estimate) with nUnit (what n counts), and a note.

No number in the prose is typed by hand. Each one prints from a fact, and a figure's title, caption and table draw on the same file, so a value quoted from the report equals the value in the chart.

Indexing

A draft chapter carries a noindex rule, and its report follows it. Whether the site as a whole may be indexed is a deployment setting; while it is off, every page carries noindex and robots.txt disallows every path. /sitemap.xml lists each written chapter and its report.

Citing and quoting

The how to cite page gives BibTeX for the book, and the identification section of each report gives the chapter's BibTeX entry, its citation key and its published and updated dates. The methods page describes how the estimates are made, and each report's methods section gives the chapter's own procedure.

An estimate in this booklet has an interval and a sample size wherever the data supply them. A program that quotes an estimate should quote both beside it, as the report prints them, together with its population and period, and should name the chapter and the date of its last update.