Week One as a Test Suite: Turning Onboarding Friction Into README Fixes

A new starter's first week is the closest thing most teams have to a clean-room test. They do not yet know which command to skip, which environment variable is 'obvious' or why the test suite only works if you run it from the right directory. That ignorance is not a problem. It is a measurement tool.

Most teams waste it. The new person is paired with a buddy, the buddy types the commands, and the documentation never gets tested. A week later everyone is busy again and the friction is forgotten. The README stays wrong, and the next graduate or career changer hits the same wall.

A better pattern is to treat onboarding as a repeatable audit. The README is the first pull request. Week one produces merged documentation fixes, not just a laptop with the right versions installed.

The README is the first pull request

Documentation is code with a different compiler. If a setup step is wrong, the build fails for a human. If a command is missing a flag, the new starter gets an error message that nobody has seen for two years. Those failures deserve the same attention as a red CI job.

So set the expectation early: by the end of week one, the new starter will have opened at least one pull request that improves the onboarding path. It might be a README fix, a corrected script, a missing prerequisite or a clearer error message. It does not need to be large. It needs to be merged.

This works best when the buddy is a reviewer, not a driver. The buddy can answer questions, but the new starter should follow the instructions literally first. If they get stuck, they write down the step, the error and what they expected. That note becomes an issue or a pull request.

Make setup a test case, not a tour

Give the new starter a fresh environment: a clean laptop, a fresh virtual machine or a container that has not been hand-tuned by the team. Ask them to follow the README from the top, without shortcuts. Time the process. Record where they pause, where they guess and where they have to ask.

A good README reads like a test case. It states prerequisites with versions, gives commands that can be copied and pasted, and shows expected output. 'Install the dependencies' is not a step. 'Run mise install to install the pinned runtime versions, then run make setup' is a step.

For a typical UK product team, the first hour often looks like this: clone the repo, install the runtime, install dependencies, create a local database, seed data, run the test suite, start the app. Each of those is a checkpoint. If the new starter cannot complete a checkpoint without a human, the documentation has failed the test.

Copy-pasteable means copy-pasteable

There is a special kind of documentation debt in commands that look copy-pasteable but are not. Placeholders like <your-token> are fine if the README explains where the token comes from and how to export it. They are not fine if the new starter has to guess which shell profile to edit.

Write commands for the shell the team actually uses. Include the working directory when it matters. Show the expected output for the commands that often fail silently. Add a short troubleshooting section for the three errors that everyone hits: the wrong Node version, the missing Postgres role, the port that is already in use.

And keep the reset instructions close by. A new starter will break their local environment. That is normal. The README should tell them how to get back to a known state without asking a colleague to remember a magic sequence of Docker commands.

Put documentation under CI

The only way to stop snippets drifting is to test them. You do not need to test every sentence. Test the commands that matter: the setup script, the test command, the database seed, the example API call. Extract code blocks from Markdown and run them in a container, or use a small script that executes the documented commands in order. Tools like mdsh, pytest-codeblocks or a custom Make target can be enough.

A CI job that runs the README on a clean image is a powerful signal. It catches missing dependencies, outdated flags and broken links. It also tells the team that documentation is part of the build, not a side project.

Keep the job fast. A five-minute documentation check is fine. A forty-minute tutorial replay is not. Test the critical path and leave the long narrative examples to manual review.

A checklist that fits on one screen

A lightweight onboarding checklist keeps the audit honest without turning week one into a compliance exercise:

• Fresh environment, no buddy typing commands.
• Clone, install and setup completed from the README alone.
• Test suite runs and the app starts.
• One small change made and merged through the normal pull request flow.
• Architecture overview found without asking.
• Where to ask questions is documented.
• Every friction point logged as an issue or fixed in a pull request.
• At least one documentation fix merged before the end of week one.

That is it. The checklist is not a test of the new starter. It is a test of the team's ability to explain itself.

Close the loop while the kettle is still warm

Onboarding friction has a short half-life. Fix it in week one, while the new starter can still remember why a step was confusing. Pair for thirty minutes on the README pull request. Review it quickly. Label it as an onboarding fix so it does not sit in a backlog behind feature work.

Add a line to your definition of done: if a new starter needed manual help for a setup step, the documentation gets updated in the same week. That turns a one-off rescue into a permanent improvement.

Graduates and career changers are ideal auditors

UK teams hiring graduates and career changers get a particular kind of documentation test. They may know how to code but not how your organisation names things. They will not recognise the internal acronym for the deployment pipeline. They will not know that 'the staging box' means a specific machine in a specific office.

That is useful. Ask them to write down every question before asking it. Some questions will be answered by the README; others will reveal a missing explanation. Define acronyms. Link to the architecture diagram. Explain the difference between the local, test and production environments. Use plain English where an internal shorthand would do.

A new starter who feels able to say 'this step did not work for me' is worth more than a new starter who silently struggles. The README gets better, the next hire has an easier first week and the team learns to treat onboarding as a product with real users.

The first pull request does not have to be a feature. Sometimes the most valuable merge in week one is the sentence that tells the next person where to find the database password.