Skip to content
Log in Install on Shopify

Writing

Notes on building an honest assistant.

One post so far, and the list below is the whole of it. Each piece here takes one decision inside the app, names the files it lives in, and shows the measurement it rests on — so a reader who disagrees has something to open. Below the list is the standard a post has to meet before it appears.

One post published Both dates on every piece Every claim points at a file

The list.

Six rules a piece has to meet to get published here.

A short list is only worth shipping if it says something you can hold us to. The first three are enforced by the build: a page in this directory ships only when it passes them, and a post is a page in this directory. The last three are a decision, written down here so that breaking one is visible.

  • Checked by the build

    Every number comes from the app, not from the draft

    Each figure on this site is marked in the HTML and compared, one by one, against the constant in the app’s own code. A post is subject to the same comparison, so a figure in a post and the thing it describes stay tied together, and the build says so the moment they drift.

  • Checked by the build

    Claims are stated plainly, in our own voice

    A scanner reads every page here and rejects a result figure, a superlative, the name of another tool, and an endorsement attributed to a merchant. It applies to a post as well. The full list of what it refuses is on the approach page.

  • Checked by the build

    Every asset on the page comes from this domain

    Fonts, scripts, images and stylesheets are all served from here, and this site sets zero cookies. The page’s own policy lets a form submit only to this domain, and the one form on the site is on the contact page, which is why reading a post leaves the same trace as reading a static file: the request for the page, and that is all.

  • A decision, not a check

    Both dates, on every post

    The day it went up and the day it last changed, side by side. A piece written a year ago says that it was, and re-dating it to look fresh would show as a change to the second date.

  • A decision, not a check

    A claim we get wrong is corrected at the top

    If a post turns out to be wrong, the correction is the first thing you read and the original sentence stays visible underneath it. Keeping both makes the record readable: you can see what we believed and when we stopped.

  • A decision, not a check

    If a machine drafted it, the post says so

    Refik answers shoppers in your storefront; the writing here is a separate job. Where a model drafted text on this site, that goes at the top of the piece, in the same place a correction would go.

What the published piece settles.

It takes one line of the app — a stock number and an optional page flag, read together — and follows it through to the four sentences a shopper can end up hearing. A summary of where it lands, so you can decide whether the argument is worth your time.

Has a page, in stock

The ordinary answer, with a link to the product. This is the case every assistant gets right, and the piece spends its time on the other three.

Has a page, shelf empty

That it has run out right now, followed by the alternatives. The familiar sentence, and the only one of the four where stock is the whole story.

Stock on the shelf, page missing

That the product exists and is in stock, and that this online store carries it elsewhere: there is a full shelf and a link that would go nowhere. The expensive case, because a stock check on its own waves it straight through.

Page missing, shelf empty

That this online store carries it elsewhere, and silence about the shelf. Both stock sentences would be unverifiable here, so the instruction withholds both — the absence of a claim is the claim.

Drawn from the single line in the app that decides this: it reads the stock number and the publication flag together, and the four cells are the four sentences that line produces. The axes move independently, which is why a stock check on its own waves the top-right cell straight through.

Where the same distinction has to hold

  • Asking for the product by name: it comes back by name, with one of the four sentences and a set of alternatives.
  • Asking for a routine built around it: the tool answers with which of four reasons applies, so the shopper learns something they can act on.
  • Asking to be told when it returns: the page check runs first, and the order is load-bearing.

What the piece measures, and what it leaves open

  • The knowledge base build prints two separate numbers: products marked as having no page, and products carrying a publication signal at all.
  • Four gaps are named and left named, including why a page is missing — the catalogue carries a flag, and a reason would be a guess.
  • One test file with more than two dozen checks is what holds the four sentences apart, and the piece points at it.

That is the shape of a piece here: one decision, the files it lives in, the sentences it produces, and the part of it that is still open. Read the whole argument in the post itself.

The shape a post has, and where each part comes from.

Written down before the first piece, on purpose: a template settled after the fact tends to be settled in favour of whatever the first piece happened to be.

Written into the piece

  • A title, the day it went up and the day it last changed
  • The measurement the argument rests on, in enough detail to be disagreed with
  • The files it describes, named, so a reader can open them alongside
  • A link to the page on this site where the same claim is checked against the code
  • A correction at the top when we got it wrong, above the sentence it corrects

Produced by the page, rather than typed

  • The contents list, built from the piece’s own headings and kept in step with them
  • Every marked figure, compared against the constant in the app that produced it
  • Each internal link, resolved against the headings that actually exist on the page
  • The stylesheet and font, served from this domain and checked for it on every build
  • The footer map, identical on every page in the directory and generated from one list

Everything on the left is a sentence we have to write; everything on the right the build produces or verifies. The shape can be settled now because each half stands on its own, and neither one needs a service, a tag or a second domain.

Questions this page can answer today.

Four things people reasonably ask of a writing index, answered from how this one works.

How do I find out when something goes up?
This page is the channel: it lists every piece with the day it appeared and the day it last changed, so a visit tells you both what is new and what has moved. If a feed is added it will be a file you can point a reader at, and it will be linked from here.
Why publish the standard before the shelf is full?
Because the standard and the shape are useful earlier than the content is, and because a directory that only appears once it is flattering tells you little about how it behaves when it is inconvenient. The footer treats every unwritten page the same way and says so in one line at the bottom.
Who writes these?
We do, and where a model drafted a passage the piece states that at the top, in the same place a correction would go. Refik’s job is answering shoppers in your storefront; it has a separate role from this page and the pieces say which one applied.
What happens to a post that turns out to be wrong?
The correction goes at the top and the original sentence stays underneath it, with the second date changing to the day we fixed it. That way the record shows what we believed, when we stopped believing it, and what we replaced it with.