Software a coworker can run without a tour

The useful test of a software product is a weekday when the person who configured it is out, and the work still has to go out. The product in this piece is a small desk a team pays for by the month: items, a draft, and a published list. The method here is this publication’s, for that kind of software.

The first success

The first successful action is smaller than a tour of the menus. Add one item, with a name, a time, and a capacity, and see it on the draft list. The person can point at the item. A tour that highlights every corner is a speech given before any work exists.

Put that action on the empty desk, in the same words the empty desk uses. The work starts on the desk itself.

Two empty screens

When there are no items, the screen says “No items yet” and offers “Add an item”. When there are items and none of them are public, it says “Nothing is public yet” and offers “Publish the draft”. Those are different empties. One means the desk has no rows. The other means the rows are still private. One picture of an empty folder leaves the person unsure which problem they have.

A failure uses the same voice. “The list did not publish. The draft is still here.” The draft remains. The screen keeps the work that was already done.

Settings for the week

Settings follow the week the team actually has. Two are enough to start. Who may publish: one role may publish, and another may edit a draft and stop there. How long a draft waits: a draft that has sat for fourteen days is marked with the date it was left, and the row is still there.

A stored column becomes a setting when someone can act on it during the week. The boundary inside the desk — what a list may take, what a publish action may change — is the same kind of boundary described in Keep a component inside its boundary.

A weekday with the owner out

The test is a morning when the person who configured the desk is not in the room. Someone else has to get the list out. They should be able to add one item — a name, a time, a capacity — and see it on the draft. They should be able to tell a desk with no rows from a desk whose rows are still private. They should be able to publish, or to see that their role stops at the draft, without a tour and without a call.

If the morning requires a call, the screen is still depending on the person who wired it. That is the failure this piece is about. A highlighted tour of the corners, given last month, will not be in the room either.

Two empties, written as sentences

“No items yet” sits with “Add an item.” “Nothing is public yet” sits with “Publish the draft.” The first means there are no rows. The second means the rows exist and the public list does not. One illustration of an empty folder makes the coworker guess. Guessing is the tour, conducted alone.

A failure uses the same plain voice. “The list did not publish. The draft is still here.” The draft remains on the screen. The work already done is not thrown away to make the error look simple. If the draft disappeared, the screen would be a third empty, and it would be lying.

Settings that match the week

Two settings are enough to start, and both are actions someone takes on a real week.

Who may publish: one role publishes, another edits a draft and stops. The second person sees the stop in words, not as a missing button they have to discover by failing.

How long a draft waits: a draft left for fourteen days is marked with the date it was left. The row stays. Fourteen days is this example’s mark, not a rule from a specification. Say the number on the setting, so the next person can change it for a shorter week.

A stored column that nobody can act on is not a setting yet. It is a note the product kept. Do not put it in the settings list until a weekday uses it.

Where the first action sits in the file

“Add an item” belongs at the start of the document, in the same words the empty desk uses. Charts, a tour, and a drawer of unused columns can be painted around it. With the style sheet blocked, the add action is still first. That is the same order as a booking page that puts the booking action before the gallery: Build the page in the order people meet it.

The control that publishes has conditions too. Ready, a press that says the work is happening, a failure that keeps the draft, and a disabled publish when the role may not publish, with the reason beside it. Those drawings are the ones in Designing every state of a control. The desk does not get a single still picture of a green button and call itself finished.

The morning the list is empty

The coworker arrives to an empty desk. The sentence on the screen is “No items yet,” and the action is “Add an item,” in those words, at the start of the document. A chart of last month, a tour highlight on a menu, and a drawer of columns nobody has filled are not on the way to that action. They can exist. They are painted around it. With the style sheet blocked, “Add an item” is still the first thing the reading meets.

If the empty sentence is clever instead of literal, the coworker spends the morning decoding it. “Your space is ready” does not say the list is empty, and it does not say what to press. The empty state is a sentence about the actual problem plus the action that fixes it. That is the whole drawing. A mascot is not a substitute for the sentence.

There is a second empty, and it is not this one. “No drafts waiting” means items exist and nothing is mid-edit. Using the first empty picture for the second tells the coworker to add an item when they should be looking for a draft. Write both sentences down. If you only have one picture, you have not drawn the desk.

Publish is a role, not a color

One role publishes. Another edits a draft and stops. The second person sees the stop in words: “You can edit. You cannot publish.” A missing button, with no sentence, is a puzzle. They will click around the drawer looking for the publish they saw in the tour. The tour is how that puzzle gets taught, and the tour is what fails when the person who recorded it is out.

The publish control has conditions. Ready, when the role may publish. A press that says the work is happening, with the words still on the control. A failure that keeps the draft and says the public list did not change. Disabled, when the role may not publish, with the reason beside it. A green button in a still picture is one of those, the ready one, and only on a good day. The piece on control conditions is the set. The desk does not invent a private dialect of states.

Fourteen days is written on the setting

A draft left for fourteen days is marked with the date it was left. The row stays. Fourteen is this example’s mark so the story has a number you can point at. It is not a requirement from a specification, and another desk can pick a shorter week. The number is on the setting, in words, “Drafts left this long get a date stamp,” so the coworker who is covering can change it without reading a changelog.

A column that nobody acts on does not belong in the settings list yet. If no weekday uses it, it is a note the product kept. Notes in the settings list look like obligations. The coworker will try to fill them and will not know when they are done. Keep the list to the two settings a week actually touches, until a third weekday shows up and needs a third.

What you leave on the chair

The person who configured the desk leaves three things, and none of them is a tour. The empty sentences, both of them. The sentence about who may publish. The number on the draft setting, with the fact that it is this desk’s mark. A coworker should run a small week from those three: add an item, leave a draft, fail a publish on purpose if their role cannot publish, and see the draft survive.

If those three are missing, the tour will be recorded to cover the gap, and the tour will be wrong the week the labels change. Fix the three sentences. The tour can stay unrecorded. That is the test this plate is for.

A week you can finish

Give the coworker a week that fits on a card next to the chair: add one item on Monday, leave it as a draft, try to publish in the role that cannot publish, read the reason, switch to the role that can, publish, and find the draft date stamp still telling the truth about when it was left. If any step needs the tour, the sentence for that step is missing. Write the sentence and run the week again. The plate is finished when the week can be done from the sentences alone.