PIMP MY IDEBack to dispatches
October 11, 2026 / documentation / first-run proof

A README is an interface. Put a stranger behind the wheel.

A clean Markdown preview can hide a broken first run. Watch a real reader use a clean machine, speak aloud, and hit every unstated assumption.

Do not rescue the test. Every hint you give is a missing line in the README.

The author is a bad first user

Terence Eden paid people €25 for an hour to follow the ActivityBot README while sharing their screens and speaking aloud. Across sessions, readers found a wrong demo link, unclear file-renaming steps, unexplained terms, confusing section order, and no clear account of what the software would do. Eden revised the README after each session. The total cost was around €150.[1]

The useful move was not a larger style guide. It was contact with the point of failure. A maintainer silently supplies missing context. A new reader cannot.

Your explanation is not part of the installation unless it is written down.

Give the README one job

GitHub says a README is often the first item a repository visitor sees. Its suggested core answers are concrete: what the project does, why it is useful, how to start, where to get help, and who maintains it. GitHub also recommends relative links for files inside the repository because absolute links may fail in clones.[2]

That is enough to set an honest first-run contract. The opening screen should identify the product and the outcome. The next section should state prerequisites. The command path should end in one observable success state. Recovery belongs beside the step that can fail.

Do not splice a lesson into a repair card

Diátaxis separates tutorials from how-to guides by user need. A tutorial supports study and manages a safe learning path. A how-to guide supports work and helps a competent reader complete a task that may branch.[3]

A README can point to both, but its first-run path should not change purpose halfway through. If the reader is learning, choose one controlled route with exact tools and a reversible result. If the reader is deploying real work, state the assumptions, branches, risks, and rollback path.

Watch behavior, not agreement

Ask the reader to start from a fresh account, container, virtual machine, or spare device. Do not preinstall the dependency you want to test. Ask them to speak each decision aloud. Record the command, expected result, actual result, and the sentence that sent them there.

Fix the first blocking defect after the session. Then hand the new version to another reader. One person can reveal a problem. The next person tests whether the repair works without the author's voice in the room.

Interactive test planner

README road-test dyno

Traditional purpose: a checklist, test profile, progress display, and copyable session card. The four stations represent preparation work. Selecting them does not prove that a reader completed the run.

PromiseIsolateObserveRepairRetest

Set the road test

Choose the reader context, then select the preparation work included in your test script.

Choose reader profile
Select road-test preparation stations
NEW USER / FIRST RUN0 OF 4 STATIONS SELECTED

Test route

Use one controlled path. Explain basic actions and keep the run reversible.

TEST SCRIPT NOT READYNo preparation station is selected. A reader run has not been performed.
Sources read / October 11, 2026 UTC

Source log

Open the evidence boundary
  1. Terence Eden, "I paid people to try and follow my README", published and read October 11, 2026. This supplies the ActivityBot test format, participant payment, total cost, reported defects, and revision between sessions.
  2. GitHub Docs, "About the repository README file", read October 11, 2026. This supports the README's role, suggested core contents, repository display behavior, and relative-link guidance.
  3. Diátaxis, "The difference between a tutorial and how-to guide", read October 11, 2026. This supports the distinction between study-oriented tutorials and task-oriented how-to guides.
  4. Hacker News discussion, item 50042219, verified through the official HN API and read October 11, 2026. We used the thread only as a current-interest signal.

Evidence boundary: Pimp My IDE read the named pages. We did not observe Eden's sessions or test ActivityBot. The interactive dyno prepares a test card. It does not run a reader study, inspect an environment, or prove that a README works.