Home/Blog/The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README
human + AI workflows
The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README
The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README In many collaborative environments, the README file can serve as an initial guide. It
18 MIN READ
11 Oct 2026
human + AI workflows
The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README
In many collaborative environments, the README file can serve as an initial guide. It aims to provide clear guidance, though sometimes that clarity can be elusive. Effective documentation, whether for a software project, a team process, or an operational guideline, is fundamental to efficient work. But what happens when that clarity is undermined by ambiguity or unstated assumptions? I decided to find out firsthand, embarking on an experiment designed to expose the hidden friction points in instructions, to truly understand what happens when I paid people to try and follow my README.
01The Experiment: Unveiling the Gaps in My Own Instructions
My premise was simple: create a moderately complex set of instructions for a non-technical task, package it as a
Want your team to run this workflow with AI-native execution?
workflow README, and pay people who had never seen it to follow those instructions exactly. I wanted to observe where they hesitated, improvised, or quietly made assumptions.
The task involved setting up a small project repository, completing a series of configuration steps, generating an output file, and submitting it for review. None of the individual steps was especially difficult. The challenge was that the steps depended on one another, and a mistake early in the process could remain invisible until the final submission.
I recruited five participants with different levels of technical experience:
A university student who used Git occasionally
A project manager familiar with documentation but not command-line tools
A software developer who worked in a different technical environment
A designer with no repository experience
An operations specialist accustomed to following procedural checklists
Each person received the same README, the same starting files, and the same modest payment for completing the task. I also told them that I was testing the instructions, not their ability. They could ask questions, but I would record each question and avoid helping unless the task became impossible.
Often, in direct collaboration, the author might be readily available for questions. A confused reader can send a message, wait for a reply, and continue. A README is often expected to work without that safety net.
02What I Expected to Learn
Before the experiment began, I predicted that the least technical participants would struggle most. I expected questions about installing tools, navigating folders, and understanding basic version-control terminology.
I was partly right, but I had misunderstood the nature of the problem.
The largest obstacles were not advanced concepts. They were small gaps between what I had written and what I thought I had written. The README contained instructions such as:
text
Run the setup command, then update the configuration and regenerate the output.
To me, this seemed clear. To participants, it raised several questions:
Which setup command?
From which directory?
Should the configuration be updated before or after the command?
Which configuration file?
What does “regenerate” mean?
How would they know whether regeneration worked?
Was the existing output supposed to be deleted first?
I had treated context as if it were part of the document. It was not. Context existed in my head, so I failed to notice its absence on the page.
03The First Sign of Trouble: People Read Differently
The first participant completed the opening steps quickly, then stopped at a sentence I considered obvious:
Copy the example environment file and fill in the required values.
They asked where the copied file should be placed. I checked the repository and realized there was only one plausible location. My immediate thought was, “They should be able to infer that.”
That thought became a recurring warning sign.
If a reader has to infer something, the author has made a design choice—whether intentional or not. Sometimes inference is harmless. Sometimes it introduces a branch in the process. Once readers begin choosing among possible interpretations, they are no longer following instructions; they are designing their own procedure.
Another participant interpreted “example environment file” as a file named example.env. The actual file was named .env.example. The difference was minor to me because I knew the project’s naming convention. It was not minor to someone searching through a directory of unfamiliar files.
The participant eventually found the right file, but only after opening several unrelated files. That time did not appear as a dramatic failure. It was simply friction: a pause, a guess, a search, and a growing sense that the task was harder than advertised.
04Measuring Friction Instead of Just Failure
A conventional usability test might ask whether participants completed the task. Four of the five did. If I had measured only completion, I might have concluded that the README was successful.
That conclusion would have been misleading.
I tracked several additional signals:
Time spent on each section
Questions asked
Backtracking to earlier instructions
Commands entered incorrectly
Files opened in search of context
Moments of visible uncertainty
Whether the final output met the required format
The results were revealing. The participants who completed the task still spent between 20 and 45 minutes dealing with ambiguity. One person followed an incorrect interpretation all the way to the end, producing an output that looked valid but omitted a required field.
This distinction is important: documentation can be technically usable while still being expensive to use. A reader may finish the process, but only by spending unnecessary time, asking for help, or relying on luck.
A successful outcome does not prove that the path was clear.
05The README Had Hidden Prerequisites
The next issue involved prerequisites. My README listed the tools needed for the task, but it did not explain how to verify that they were installed or which versions were supported.
I had written:
text
Requirements:
Git
Node.js
npm
That list looked tidy. It was also incomplete.
One participant had Node.js installed but was using an older version that produced an obscure dependency error. Another had Git installed but had never configured a username or email, so the first commit command failed. The operations specialist used a managed work computer where a security policy prevented one of the commands from running.
None of these conditions was unusual. What was unusual was my assumption that “installed” meant “ready.”
A stronger prerequisite section would have included checks such as:
bash
git --version
node --version
npm --version
It would also have stated the supported version range and described what to do if a check failed. More importantly, it would have separated required tools from optional background knowledge.
For example:
You do not need prior knowledge of Node.js. You do need permission to install packages and run commands in a terminal.
That sentence would have prevented several minutes of uncertainty.
06Commands Are Not Self-Explanatory
I had also assumed that commands could stand on their own. The README included blocks like this:
bash
npm install
npm run build
npm run export
A technically experienced reader might recognize the sequence. Others did not know whether each command should be run separately, whether the second command depended on successful completion of the first, or what output to expect.
One participant pasted all three commands at once. When the first command failed, the remaining commands still ran and generated a confusing cascade of errors.
The revised version added short explanations:
bash
Install the project dependencies.
npm install
Create a production build.
Run this only after npm install completes successfully.
npm run build
Generate the final output file.
npm run export
I also added expected success indicators:
After npm install, you should see a completion message and a new node_modules directory. Warnings may be acceptable; an exit code other than zero is not.
This was more verbose than the original, but it reduced the reader’s need to interpret the tool’s behavior. Good instructions do not merely say what to type. They explain how to recognize progress and failure.
07Ambiguity Often Appears in Ordinary Words
Some of the most damaging phrases in the README were not technical terms. They were ordinary words:
“Soon”
“As needed”
“Use the appropriate value”
“Make the necessary changes”
“Run the usual checks”
“Submit the generated file”
“Clean up the directory”
Each phrase felt efficient because it avoided unnecessary detail. In practice, each transferred a decision from the author to the reader.
What counts as “soon”? Which value is appropriate? Which checks are usual? Should cleanup remove temporary files, generated files, or everything untracked?
I replaced vague wording with observable actions. Instead of:
Update the settings as needed.
I wrote:
Open config/settings.json. Change "environment": "development" to "environment": "production". Do not change the port or outputPath fields.
Instead of:
Submit the generated file.
I wrote:
Upload dist/report.csv to the submission form. Do not upload the dist folder or the source files.
The revised instructions were less elegant, but they were more dependable. Documentation is not a writing contest. Its purpose is to produce a shared result.
08The Importance of a Known Starting Point
Another problem emerged when participants began from slightly different states. The README said to “clone the repository,” but it did not specify whether they should use the default branch, a release tag, or a provided archive.
Two participants started with a newer version of the repository than the one I had used while writing the instructions. A file had moved, and one command behaved differently. The README was not universally wrong; it was accurate for one snapshot.
That experience changed how I think about reproducibility. Instructions need a defined starting point. Depending on the project, that may mean specifying:
A repository URL
A branch or tag
A commit identifier
A required operating system
A clean working directory
A particular account or permission level
A known input file
I added a section called “Before you begin”:
text
Use the v1.3.0 release tag for this exercise.
Your working directory should contain no previous copy of this project.
You will need permission to create files and install local dependencies.
This small amount of information eliminated an entire category of avoidable differences.
09What the Questions Revealed
I kept a list of every question participants asked. The list became a more useful revision guide than my own rereading.
Questions generally fell into four categories.
Location Questions
These included:
Where should I run this command?
Which folder contains the file?
Where does the output appear?
Do I save this beside the example or replace it?
The solution was to name paths explicitly and state the working directory before command blocks.
Sequence Questions
These included:
Do I run this before or after editing the file?
Should I commit before generating the output?
Can I skip this step?
Do I repeat the setup if I already ran it?
The solution was to number dependent actions and explain when a step could safely be repeated.
Interpretation Questions
These included:
What does “valid” mean?
Which fields are required?
Is this warning a problem?
What should the final result look like?
The solution was to provide examples, constraints, and acceptance criteria.
Recovery Questions
These were the questions I had neglected most:
What do I do if this command fails?
Can I restart without deleting everything?
How do I undo the previous step?
How can I tell whether I have made a mistake?
A process that describes only the happy path is incomplete. People do not need a complete encyclopedia of possible errors, but they do need a few recovery routes for predictable failures.
10Adding Checkpoints
The most effective revision was the addition of checkpoints. After each meaningful stage, the README now asked the reader to verify a specific condition.
For example:
Checkpoint: At this stage, the project directory should contain config/local.json, and the file should include a non-empty apiUrl value. If either condition is not true, stop and review Step 3.
This prevented errors from accumulating. In the original process, a participant could make a mistake in Step 2 and discover it only after Step 8. By then, the source of the problem was difficult to identify.
Checkpoints also reduced anxiety. Participants reported that they felt more confident when the README told them what “correct so far” looked like. Verification was not merely a debugging aid; it was reassurance.
11The Difference Between Documentation and Training
The experiment also exposed a boundary between documentation and training.
A README should not assume that every reader needs an explanation of the entire technology stack. At the same time, it should not assume that readers already understand the author’s vocabulary.
I began linking unfamiliar terms to short explanations rather than embedding long lessons in the main flow. The README defined only what was necessary to complete the task and moved deeper background into separate sections.
This produced a clearer structure:
What the task accomplishes
What is required
Quick start
Step-by-step procedure
Verification
Troubleshooting
Background and reference material
The main path remained focused, while readers who wanted more context could continue to the supporting sections.
12The Revised Test
After rewriting the README, I paid three new participants to repeat the process. This time, I gave them no verbal introduction beyond the task description.
The results were substantially better:
Fewer questions about file locations
No commands run from the wrong directory
Faster identification of failed prerequisites
No invalid final submissions
Less backtracking
More consistent completion times
The most important change was not that everyone moved quickly. It was that their behavior became predictable. They followed roughly the same path and reached the same result without relying on private knowledge.
That is the real purpose of clear documentation: not to make every reader feel brilliant, but to make the process independent of the author’s presence.
13What I Would Test Next Time
If I repeated the experiment, I would make several changes from the beginning.
First, I would recruit participants closer to the intended audience. The original group was useful because it exposed broad usability problems, but a README for experienced developers may require different tests than a README for customers or internal operators.
Second, I would test on multiple operating systems. A command that works on macOS may fail on Windows because of path syntax, shell behavior, or permissions.
Third, I would include a participant who is under realistic time pressure. Calm experimentation can hide problems that become obvious during a deployment or incident.
Fourth, I would test updates, not just first-time setup. Documentation often becomes inaccurate gradually as dependencies, filenames, and workflows change. A README that works today may quietly decay over several months.
Finally, I would ask participants to explain what they believed each step was doing. Completion data shows where people stop; explanations reveal the mental models that led them there.
14A Practical Checklist for Testing Your Own README
You do not need a large research budget to perform a useful documentation test. A simple version can be done with one or two people who were not involved in writing the instructions.
Before the test:
Give the participant a clean starting point.
Avoid explaining the process verbally.
Define what successful completion means.
Ask permission to record questions and observations.
Prepare a way to restore the starting state.
During the test:
Do not immediately rescue the participant.
Record the exact wording that causes hesitation.
Note when the participant searches outside the README.
Watch for guesses that happen to produce the right result.
Ask what they expected to happen before offering help.
After the test:
Group problems by cause rather than by participant.
Replace assumptions with explicit information.
Add examples where readers must choose a format.
Add checkpoints after consequential steps.
Retest from a clean state.
Remove instructions that are no longer necessary.
One caution is worth emphasizing: do not turn every question into another paragraph. More documentation is not automatically better documentation. If participants repeatedly ask a question, identify why. Perhaps the workflow itself is confusing, the file structure is poorly named, or the step belongs in a script rather than in prose.
15The Broader Lesson
Paiying people to follow my README changed my understanding of clarity. I had thought of documentation as a record of the process I already knew. The experiment showed me that it is better understood as an interface.
An interface has users, states, feedback, errors, and expectations. It succeeds when people can make progress without needing to understand its creator’s internal model. A README works the same way.
The reader does not see the decisions that shaped the project. They see filenames, commands, headings, and results. They cannot know which details are essential unless the document tells them. They cannot distinguish a warning from a failure unless the document explains the difference. They cannot ask what the author meant unless the author has anticipated the question.
That is why paying strangers to try the process was so valuable. Their confusion was not an inconvenience added to the work. It was evidence about the work.
16Conclusion: Clarity Is an Engineering Property
The final lesson was uncomfortable but useful: I was not the best judge of whether my README was clear.
I knew the intended path, the reasons behind each command, and the shape of the expected result. That knowledge made the document appear more complete than it was. I read what I meant, not only what I had written.
The participants did not have that advantage. They exposed missing prerequisites, ambiguous wording, hidden assumptions, weak error handling, and undefined success criteria. In doing so, they transformed a vague feeling that the README “could be better” into a practical list of improvements.
The next time I write instructions, I will treat them as an executable process rather than a piece of supporting prose. I will define the starting state, name the actions precisely, show expected results, include recovery paths, and test the document with someone who does not share my context.
Because the question is not whether the author understands the README.
The question is whether a new reader can use it successfully when the author is not there.
For I paid people to try and follow my README, Nonilion can be used as the practical AI-office example: a shared workspace where human teammates and AI agents keep discussion, decisions, and execution connected.
The reason I paid people to try and follow my README keeps returning to Nonilion is simple: the topic becomes more useful when it turns into coordinated work, not just another article, chat, or dashboard.
17Why This Trend Matters for Nonilion
This trend matters to Nonilion because it points to a bigger change: teams are moving from simple calls toward persistent, AI-supported collaboration spaces. Nonilion can bridge live presence, meeting context, avatars, and follow-up work so the trend becomes a usable workflow instead of a headline.
18Shareable Extracts
The trend is not just "The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README" - it is a signal that team coordination is becoming the next competitive edge.
Hot take: the teams that win from this shift will not be the ones with more meetings; they will be the ones with clearer shared context after every meeting.
If the unspoken contract of clarity: what happened when i paid people to try and follow my readme keeps moving this fast, remote teams need a workspace where conversation, presence, and follow-up stay connected.
The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README In many collaborative environments, the README file can serve as an initial guide.
It aims to provide clear guidance, though sometimes that clarity can be elusive.
19Social Hooks
Everyone is talking about The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README. The overlooked part is what happens to team workflows after the headline fades.
The uncomfortable question behind The Unspoken Contract of Clarity: What Happened When I Paid People to Try and Follow My README: are teams adapting their collaboration systems fast enough?
This is not a meeting trend. It is a coordination trend, and products like Nonilion sit right in the middle of that shift.
20Sources and Author
Sources
No direct external source URLs were available for this run.
Author
This article on I paid people to try and follow my README was generated by the Nonilion AI blog workflow using web research inputs and AI-assisted synthesis.
