Job docs-readme-onboarding-proven-by-cold-start · revised 11 October 2026
A README and setup guide proven by a cold start on a clean machine
The setup guide for one repository is rewritten and then followed on a clean machine until the project runs and its tests pass. Every command you read in it has been run.
You might be seeing
- New developers ask the same setup questions and the answers are not written anywhere
- The setup instructions name tools, versions or accounts that no longer exist
No passwords, keys, card details or admin invites needed to start.
What usually happened
A repository's README describes a setup that no longer works, or never did: missing prerequisites, undocumented environment values, steps in the wrong order, commands that assume the author's machine. Nobody notices because everyone who could follow it already has a working setup. The job rewrites the first-run documentation and proves it on a machine that has never seen the project.
Who it’s for: An engineering lead, founder or agency handing a repository to a new hire, a client or a successor, whose setup instructions are out of date or live in one person's head.
Usually starts when: A new developer lost days getting the project to run, a handover to a client or another team is coming, or the only person who knows how to start it is leaving.
The result: Following only the new README on a clean environment takes a person from a fresh clone to a running application and a passing test run, with no step that needs someone to explain it. You receive the pull request with the README and the record of the cold-start run.
Check whether this job fits
Answer from what you know about the project. These checks show whether the setup can be proven on a clean machine without production access.
Checks you can run yourself
Watch someone try it
Ask a colleague who has not set the project up to follow the current README on a spare machine or fresh container, and write down every point where they stop or ask a question.
Look for: Each stopping point is a missing or wrong step. A handful means a quick rewrite; a project that cannot be started at all points to a repair job before documentation.
What you get
- A pull request with the rewritten README, the optional extra page and a sample configuration file with invented values
- A prerequisites table with versions, and an environment-values table with what each value means
- The cold-start record: each step, its command, its result, the time it took and every change made to the instructions
- A list of anything that could not be proven and why, such as parts that need production services
Included
- One repository: its README and, if wanted, one extra setup or contributing page
- Follow the existing instructions on a clean environment first and record each failure, missing tool, wrong version and undocumented environment value
- Rewrite the setup steps in order, naming each prerequisite with its version and where to get it, each environment value with a safe invented example and meaning, and the commands that start the application and run its tests
- Prove the new instructions with a cold-start run on a clean environment that holds only the stated prerequisites, and correct the steps until the run passes without improvising
Not included
- Architecture documentation, API reference, user manuals or marketing copy
- Changing code, build files or scripts to make installation easier, beyond a sample configuration file; those are separate jobs
- Documenting production, real secrets or third-party accounts: examples use invented values
- More than one repository, translations, or keeping the documentation current over time
- A promise that the steps work on every operating system: only the platforms named in the agreement and actually run are covered
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
On a clean environment holding only the stated prerequisites, following only the README takes a person from a fresh clone to a running application that answers the agreed health check, and the agreed test command passes, with no improvised step.
Evidence: The cold-start record with each command, its output and the environment description, from the final source revision.
Every command in the setup, run and test sections of the README was executed during that run, and every correction made along the way is listed in the record.
Evidence: The record's list of commands and corrections compared with the README text.
Every prerequisite is listed with a version and a source, every environment value has an invented example and a meaning, and the sample configuration file starts the application locally.
Evidence: The two tables, the sample file and the run that used it.
A person on your side who has not set the project up follows only the README and reaches the same result; if no such person exists, a second clean run from the final commit by an independent reviewer stands in, and the record says so.
Evidence: That person's account, or the reviewer's run, and the questions asked, each answered in the final README.
Sign-off. You or your named reader follow the guide, sign off in writing and merge the pull request. Payment follows sign-off.
If it fails. If the agreed checks do not pass, you do not pay for this fixed scope. If the project cannot run on a clean machine without code changes, we list the blocking steps and stop, and a repair job needs its own agreement.
When it fits, and when we stop
It fits when
- The project can run locally or in a container with synthetic data and no production credentials
- You name the platforms the instructions must work on; a clean Linux environment is the default and others only where we can reach one
- The code can be shared through an authorised company-controlled route after agreement, and a named person can review and merge the pull request
We stop and tell you if
- The project cannot run without production credentials, private services or data that you cannot replace with invented values
- The project does not build on a clean machine for reasons that need code changes: we report the blocking steps and you choose a repair job
- A required tool cannot be installed in our test environment, for example because of its licence or a hardware dependency
What could go wrong
The work is one pull request that changes documentation and adds a sample configuration file. Closing it before merge changes nothing; after merge your maintainer can revert it like any other commit.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| The guide works in our clean environment but not on your readers' machines. | The platforms are named in the agreement, the clean environment is described in the record, and the guide says which platforms were run and which were not. |
| The guide drifts out of date as the code changes. | The record states the source revision and the date it was proven. Keeping it current is a separate monthly service, and a short check you can repeat is part of the handover. |
| A sample value looks like a real secret or is one. | Every example value is invented and clearly marked, and the reviewer checks that none matches a real credential format in use. |
| A step depends on something only the author has installed. | The cold start runs on an environment that contains only the stated prerequisites, so hidden dependencies fail visibly. |
An independent reviewer repeats the cold start from the final commit, following only the README, and checks that no step relies on something that is not written down. Your authorised maintainer reviews and merges under your existing rules.
Need to keep it working?
Keeping the guide and the tests in step with the code as it changes is offered separately as a monthly service.
Ongoing work is separately scoped and quoted: no monitoring, response-time guarantee or automatic subscription is included in this job.
Explore an ongoing engineering lane, or mention the responsibility you need in your enquiry.
What you can check
This is a new service. We have not delivered this job for a client yet.
Other ways to get this done
- GitHub lists what a README should answer: what the project does, why it is useful, how to get started, where to get help and who maintains it. A maintainer can use that as a template. docs.github.com
- The Diataxis framework separates tutorials, how-to guides, reference and explanation, which helps decide what belongs in a setup guide and what belongs elsewhere. diataxis.fr
Questions
What is a cold start?
Following the documentation on a machine that has never seen the project, with nothing installed except the stated prerequisites, from a fresh clone to a running application and passing tests. Anything the author's machine supplied silently shows up as a failure.
Will you change the code to make it easier to install?
No. We document what exists and add a sample configuration file. Changes to build files or code are a separate job.
Does it work on every operating system?
Only on the platforms named in the agreement and actually run. The guide says which.
Can you keep it up to date as the code changes?
Not in this fixed job. A monthly service that updates tests and documentation after behaviour changes is available as a separate agreement.
Send an enquiry
Send us
- The language and framework in general terms, and how a developer starts the project today, as a short description
- Who the guide is for: a new hire, a client's developers or a successor, and the platforms they use
- Whether a README or setup page exists today, even if it is out of date
- Do not send code, credentials, real environment values or customer data in the first enquiry
Later, once you agree
- The agreed source revision through an authorised company-controlled code-export route, with a branch route for the pull request
- The current README or setup notes, and a person who can answer questions about how the project is really started
- Invented or test-only configuration values, and the named person who accepts the guide
You own the repository and its documentation. We work on a copy in an isolated workspace through a company-controlled identity, never a personal login, with invented configuration values. You review and merge the pull request; we do not touch production or hold any key.
Email fallback: open your mail app
If website submission is unavailable, review and send the fallback email yourself. An email fallback is not a website receipt. Or write to hello@syntheticindustry.ai with “docs-readme-onboarding-proven-by-cold-start” as the subject.