Turn repeated reader questions into better instructions

When readers repeatedly ask the same question, save the question alongside the instruction they encountered and the action they were trying to take. Investigate that combination before writing a longer answer. The problem may be an unclear term, a missing decision rule, a hidden explanation, or a task your method does not actually cover.

For an author skill, the useful change is the one that helps the next reader proceed correctly. Adding the answer to a large reference file is not enough if the companion never uses it at the relevant step.

Start with one recurring misunderstanding. Write a small repair, compare it with the old instruction, and test the revised task. Keep the result open until you have evidence that the change helped. A quieter inbox alone cannot tell you whether readers understood, stopped trying, or found another source of help.

The example in this article is fictional. It shows how an author of a practical portfolio book could repair one instruction. Reader questions, draft changes, and possible retest outcomes are illustrative, not reports from customers or an executed experiment.

Imagine your book teaches creative practitioners to explain the decisions behind a portfolio project. Your companion currently says:

Show your process before presenting the final work.

You encounter questions such as:

• “Do I need to include every sketch?”
• “How much process is enough?”
• “I have forty screenshots. Which ones belong here?”

It is tempting to answer each separately. But they may share an unresolved decision: which evidence helps a viewer understand the work?

Do not collapse the questions into “readers do not understand portfolios.” That label is too broad to guide a repair. Preserve the actual question and enough context to distinguish a beginner choosing material from an experienced practitioner asking about a special case.

For real feedback, record the instruction version and whether the reader saw it. A question received by email may concern the book, an older skill, or something another person recommended. It cannot automatically be assigned to the latest companion instructions.

Keep names and unnecessary personal details out of your working log. What matters here is the task, the explanation, and the point of uncertainty.

Use one row per meaningful instance, then group related rows:

The cause is still a hypothesis. A reader might understand the criterion but lack permission to show the relevant material. They might be working on a project that has no useful intermediate artifacts. Those situations need different responses.

Also distinguish multiple messages from multiple readers. One person asking three follow-up questions can expose a significant problem, but it is not three independent reports of recurrence. Keep the counting unit visible when you decide how broadly to change your instructions.

A discussion among technical writers illustrates the difference. u/kaycebasques worried about a generic FAQ label:

“I worry that the people who frequently repost the same questions about salary would overlook a pinned thread titled "FAQ".”

This was a participant's concern about a forum, not a measured finding about which title works best. The author-facing lesson is to inspect where the explanation appears and whether its label matches the reader's question.

In the portfolio companion, perhaps the decision rule is already in a section called “Narrative integrity,” while readers ask which screenshots to choose. Rewriting the rule may be unnecessary. The repair might be to bring it into the selection step and label it “Which process images should I include?”

Look at the actual experience. Did the companion show the relevant explanation? Did it send a link without answering the immediate question? Did it quote a principle but omit the example that makes it usable? These are different failures, even if the reader's final question sounds the same.

W3C's supplemental guidance on clear instructions recommends placing instructions before or beside the activity, including the necessary steps, and offering helpful examples. That is design guidance, not evidence that a particular wording will solve your readers' problem.

For this fictional method, the author decides the real omission is the selection criterion. The revised instruction becomes:

Choose up to three process items that help a viewer understand an important decision in this project. For each item, name the question you faced, the option you chose, and what the item shows about that choice. Leave out material that repeats a point already established. If you cannot show the original material, describe the decision without implying that a reconstruction is the original evidence.

The number three is a teaching constraint in this invented exercise, not a universal portfolio rule. The improvement is the explicit relationship between evidence and decision.

Add a small example:

The companion should ask what an item demonstrates before praising the size of the collection. Forty screenshots are not automatically better evidence than two well-chosen comparisons under this method.

A repair should not quietly turn the book into a different approach. If your method values uncertainty and exploration, do not rewrite every process account as a tidy story in which the practitioner always knew the answer.

The revised instruction should allow a reader to say, “We tried this because we were uncertain, and it did not resolve the question.” That can be useful evidence of a decision process. Requiring every example to end in success would distort the method.

A fiction writer, u/AcidicSlimeTrail, described the gap between intended and received meaning:

“Yet when I write what I think is a very obvious metaphor, everyone takes it at face value and I get met with confusion or the assumption my writing is nonsense.”

That is their account of interpreting fiction, where different readings may be legitimate. A practical instruction has a different job: when a reader needs a particular distinction to perform the task, the author should make that distinction inspectable. Do not assume that what feels obvious to you is already present on the page.

If the skill still asks readers to upload every artifact before applying the selection rule, the experience has not caught up with the explanation.

Write the behavior you want:

1. Ask the reader to name one decision in the project.
2. Ask which available item would help someone understand that decision.
3. Explain why the item fits or what is missing.
4. Repeat only for a different decision that needs evidence.
5. Review the selected set for duplication and unsupported claims.

If the reader has no suitable item, offer an honest alternative within the method. Do not fabricate an earlier sketch or invent a story about why a choice was made. A reconstruction can be useful only if it is clearly described as a reconstruction.

Check related examples and templates for the old wording. A revised main instruction and an unchanged example demanding a complete timeline would send conflicting signals. Keep the repair small, but make it consistent wherever the relevant step appears.

Do not ask only, “Is the new wording clearer?” A reader can agree and still choose all forty screenshots.

Give a suitable reader the revised instruction and a small set of candidate materials. Ask them to choose items and explain why. Observe whether they connect the evidence to distinct decisions. If you must repeatedly explain the criterion aloud, record that intervention; it is part of the result.

Here is a proposed retest record. The outcomes are possibilities, not completed findings:

Keep the old case after a successful repair so later edits do not remove the distinction again. The agent skill testing guide can help make that check repeatable.

For each repair, retain the question pattern, evidence for the cause, exact instruction change, affected examples, and actual retest result. Mark unresolved explanations explicitly. This gives you a record of why the skill changed, rather than a growing pile of disconnected tips.

Bring one repeated reader question and the instruction it exposed to Skillfully and choose Book onboarding. A concrete misunderstanding is a useful starting point for deciding what your companion should explain, ask, and check differently.