Lesson 5.75.7 Choose the output format: inline, artifact or structured data

In everyday life. You send a quick text to say you are late, a birthday card that someone keeps, and a form that the bank's system reads.

The format part of a brief names the output format: the shape the result comes back in, and where it goes next. Who or what reads the result next decides it.

• Inline. In the chat itself. A person reads it once, now: a quick check, an explanation, a short list. No separate file is needed.
• Artifact. A file or document of its own. A person keeps, edits, shares or approves it: a memo, a document, a slide deck, a spreadsheet. Name the type and where it must go.
• Structured data. A system or a later step reads it: a CSV file, a JSON record, a table with fixed columns. Name every field (column) and its type (date, number or text). Ask for one row per item, say how to mark a missing value, and say "no prose", meaning no paragraphs around the rows.

For the payment run, the structured-data line can read like this. "One row per open invoice, with these columns: invoice_no, vendor_name, due_date, amount, currency, action, reason, policy_section. If you cannot fill a field, leave it blank and say why in the reason column. No prose."

One task can need all three. Brightline's payment run does: a proposal CSV that a program checks, a one-page memo for Dave, and a three-line note to Maria in the chat. Each reader gets the shape it can use.

For an artifact, choose the type by what the reader will do with it. A document suits text someone reads and signs, such as Dave's memo. Slides suit a few points shown to a group. A spreadsheet suits numbers the reader will sort, filter or work out again. A dashboard suits numbers someone checks again and again, such as open invoices by week.

Format also organizes the content. In an artifact, start with what the reader must decide: "Approve Midwest Packaging 4519, decide on the Canadian invoice, then sign the run." Group items by what the reader will do with them, not by the order in which the worker found them. For example, put the invoices to approve together, and the ones on hold together.

Format decides what you can check. A CSV with one row per open invoice can be checked by a machine: the row count matches the invoice list, the totals add up, and every row has an action. Two pages of prose are hard to check except by reading them. When a decision depends on the result, ask for a shape you can check.

Ask the worker to end the result with anything it could not verify, such as an invoice it could not match to a vendor record. This is how a brief asks it to acknowledge uncertainty (5.1), and it tells you where to start your review.

Length and tone are not part of the format in this book. They are content rules, in the constraints (5.1). A size that is part of the shape stays here: "a one-page memo" is a shape, and "Dave can read it in two minutes" is a rule.

Figure 5.4. Who reads it next decides the format.