Formats›A key, in seven lines

A key, in seven lines

A reusable format for the words that go beside a number. Take it, fill it, use it again, whenever you are about to put a number in front of people who did not make it.

Download key-format.md The file you fill in. Plain text — open it in any editor, or hand it to an agent.

What this is for

This is for anybody who shows other people a number those people did not compute themselves. An index on a public page, a band on a mark sheet, a score on a dashboard, a rating beside a product. The number arrives with authority because it is a number, and the reader fills in what it means from whatever they already believed.

A key is the few plain sentences that sit beside the number and say what it is. It is not the method, and it does not defend the method. It tells a reader what your number measures, before they fill that in from what they expected.

The format decides two things for you. The key is written before the first number exists, so it cannot be fitted to results. And its last line names who and what the number cannot hear, because an instrument records only where it is placed, and nothing outside that range can lower the number.

Where this comes from: a project of mine still in progress, a number computed every hour from free animals' own sounds and movements, shown under a key written by a person before the model was asked anything. It rests on a split: a person holds the words and code computes the number. I work that split out in Split-Domain Cognition, under "Who holds the language".

The format

IT SAYS        what the number says, in one plain sentence
MADE FROM      what it is computed from, and who decided how

IT IS NOT      what a reader will take it for, each one refused
WHAT MOVES IT  what can raise it, and what can lower it
BANDS          each stretch of the range, said in words, once
NO NUMBER      what is shown when it does not know, and why

UNHEARD        who and what it cannot hear

Seven lines. The first two say what the number is, the middle four keep it from being read as something else, and the last says where it stops.

What each line is asking

IT SAYS. One sentence a person outside your field could repeat back to you correctly. Not the formula, and not the name of the index. How much the last hour sounded like what free animals do when nobody interferes with them. If the sentence needs a second sentence to be true, write the second one into IT IS NOT instead.

MADE FROM. What the number is computed from, and who set the way it is computed. Name the person or the body that decided the weighting, the threshold or the cut-offs. A number whose rules have no named author reads as a fact of nature.

IT IS NOT. What a reader will take it for. Write down each likely misreading and refuse it in plain words: not a count of animals, not a measure of any one animal, not a message from any animal. People read a number as an answer to the question they already had, so say which question it does not answer.

WHAT MOVES IT. What can make the number go up, and what can make it go down. Both directions, and the things a reader would not guess. If one change could move it either way, say so, so that a reader can tell a change in the world from a change in the instrument.

BANDS. Each stretch of the range, described once, in words. 76 to 100: the hour sounded like free action across the listened-to world. Describe what a band means and leave out any grade. Words like good, poor and healthy turn a description into a verdict, and the reader remembers only the verdict.

NO NUMBER. What appears when the instrument does not know, and the reasons it might not. A blank with a reason is information. A number shown when the instrument did not know is a guess presented as a measurement, and the reader cannot tell the difference.

UNHEARD. Who and what the number cannot hear: people, animals, plants, places. Name them. Every instrument is placed somewhere by somebody. What it cannot hear does not lower the number; it is left out. So a number can read high while the worst of what it claims to measure goes on out of its range.

The rule that is not a line

Write the key before the first number, date it, and do not change it to fit a number. A key written after the results describes the results. When the key does need to change, write the new one with its own date and keep the old one beside it, so a reader can see which key a number was read under.

A worked one

IT SAYS        how much the last hour, where microphones listen to free
               animals, sounded like what free animals do when nobody
               interferes with them

MADE FROM      a small model that has only heard and seen free animals,
               their sounds cut into numbered units; code turns its
               expectations into 1 to 100; a person wrote the weighting
               and this key

IT IS NOT      a count of animals, a measure of any one animal, a message
               from any animal, a report on what any animal did

WHAT MOVES IT  the hour's sound; and every recording accepted into the
               corpus, which can move it up or down, and neither is better

BANDS          76 to 100  it sounded like free action
               51 to 75   mostly, with stretches that did not
               26 to 50   as much that did not as did
               1 to 25    little like it, or almost nothing heard

NO NUMBER      no station could be scored, or a model did not know;
               the line below the number says which

UNHEARD        the animals in sheds, cages and pounds; no station hears
               them, and this number cannot speak for them

The number in this example is built only from animals who are free. So the more animals are confined, the fewer free animals there are to hear, and nothing in the signal falls when that happens. Without the UNHEARD line the page would show a high number while more animals were confined in sheds. The line tells the reader, before they see the number, which animals it leaves out.

How to use it

  1. Write it before the instrument is run. Date it at the top. Then run the instrument.
  2. Write IT IS NOT by asking somebody else. Show a person the number and the IT SAYS line, ask them what it means, and write down what they say. Their reading is the misreading you have to refuse.
  3. Put the key beside the number. On the same page, at the same size, where the number is. If the key is not read alongside the number, it does nothing.
  4. A person writes it. The person who holds the standard the number serves. A generated summary is the number's own account of itself, and it will be a favourable one.
  5. Keep every old key. In order, each with its date. A run of keys is how a reader sees what the number used to claim.

Three ways it goes wrong

It is written after the numbers. This happens most often, and from the outside it looks the same as a key written first. The bands get drawn where the results happened to fall, and IT IS NOT leaves out the misreading the results would have encouraged. If you have seen a number before writing the key, say so at the top.

UNHEARD becomes a disclaimer. This measure has limitations names nobody. The line is for naming who: the district with no station, the workers who were never surveyed, the animals no microphone reaches. If the line could be pasted under any number, write it again.

The bands turn into verdicts. It starts with a colour, red for the bottom band, and then a word, and soon the key grades the world instead of describing the number. Once a band says bad, readers stop reading the other six lines.

Prayas Abhinav. Licensed CC BY 4.0. Copy it, change it, build on it, including commercially. Say where it came from, and if you changed it.

Take a copy: key-format.md. Yours to alter.