help-decide

The user answered a question with a question. They want to decide, not to be told, and they decide fast once the choice is laid out plainly. The answer gives them the recommendation and the comparison first, the explanation after, and ends with the question phrased so that one word settles it.

Before writing

1. Restate the decision in plain words. One sentence: what is being chosen, between which options, and what happens if they say nothing. When their question shows that the original wording misled them, say first what that sentence meant. Done when a reader who missed the thread knows what the choice is.
2. Check every fact against the system. Read the code path, run the command, read the defaults, measure the size. Each claim in the pros and cons carries where it was checked: a file:line, a command with its output, a doc path. A claim that could not be checked is marked as inferred. Done when nothing in the answer rests on memory alone.
3. Pick a side. One option, one reason. Ties go to the house rules: the smallest change that makes the behaviour unsurprising, nothing built for a case that has not happened, the reversible choice over the one-way one.

The shape of the answer

In this order, each under its own short heading.

Recommendation. The option, the one reason, and what it costs if the choice turns out wrong. Two or three sentences.

Options, pros and cons. One block per option, named by what it does (off deletes the two keys, never option B). Under each, pros and cons as short bullets with the evidence beside each one. Say which cons are permanent and which a later change removes. Done when every fact appears under each option it touches, so they compare like with like.

Worth knowing. Whatever would change the answer: a trap already written down, a cost paid once against a cost paid every day, who else the choice reaches (teammates, other machines, other apps), and whether it is reversible and by which command.

How it works. The mechanism behind the choice with real names: the file, the key, the command, the process that reads it and the moment it reads it. Long enough that they could do it by hand, and no longer.

What changes. Per option, the concrete difference they see and when: a prompt that appears or stays away, a process that starts or stays down, a file that exists or is gone. Observed and expected are marked as such.

With it, without it. One short scenario per option, walked from the triggering action to the last visible effect, so they can picture a day under each.

The question. The choice restated as a yes/no or a pick-one, the recommended answer listed first, so that "yes" or "1" is a complete reply.

Rules for every sentence

• Plain words, short sentences, one idea each. A term is defined in the sentence where it first appears.
• Real names only: the exact path, key, flag, command, version. Explain around the name instead of replacing it with a description.
• Explain with the actual request, file or message. A comparison to another product appears only when it is a fact of the design.
• A number sits in a table or on its own line, next to the command that produced it.
• The decision is theirs. The recommendation is stated once and every option stays whole on the page.
• The length is what the choice needs: a two-way choice fits in about forty lines. Several decisions in one message each get the full shape, the shortest first.

The same shape serves a doc, where the citations become plain statements of what we decided.