Write hackathon README instructions that a teammate can check

Your teammate opens the repository and finds “run the app.” They still need to ask which folder to use, what should appear and whether the result is correct. A useful hackathon README answers those questions before the author joins the call.

Start with one complete path from opening the project to seeing its main result. Give every step an action and an observable outcome. A command that finishes without an error is only part of the check.

Pick one job the reader can finish

Suppose a fictional project lets a participant add an idea to a board. “Explore the dashboard” is too broad for a first run. “Create an idea called Water meter and find it on the board” gives the reader a finish line.

Write the path for someone who did not build the project. Name the starting page, the button and the result using the words visible in the interface. If your README says “submit” but the button says “Add idea,” change the README.

GitHub describes a README as a place to explain what a project does and how to get started. That is a useful priority when time is short: make the first successful action easy to find before adding a long account of your architecture. GitHub’s README guidance.

Put the outcome beside the instruction

This is an illustrative acceptance section for that idea board. The paths, labels and behavior are invented; adapt them to the project you have actually checked.

## Check the first successful action

Starting point: the app is running and the home page is open.
Required access: the local demo participant account described above.

1. Open the Ideas page.
   Expected: a heading named Ideas and a button named Add idea.
2. Select Add idea and enter Water meter as the title.
   Expected: the title stays visible in the form.
3. Save the form once.
   Expected: one Water meter card appears on the board.
4. Reload the Ideas page.
   Expected: the same card is still present, without a duplicate.

If the account is unavailable, stop at step 1 and report access_blocked.
The fallback screenshot demonstrates layout only; it does not prove saving works.

The reload expectation is a product decision. A temporary prototype might intentionally lose data. If that is your design, say so and change the expected result. Do not promise persistence because it sounds more complete.

Keep setup instructions immediately above this section. For each real command, state the working directory and when it is finished. If two processes must remain running, label their terminals. Copy the commands from the successful attempt rather than from memory.

Ask someone to follow the words exactly

Give a teammate the README and stay quiet during their first attempt. Record the first place where they must guess. That is usually a more useful edit than another introductory paragraph.

A small review record is enough: instruction, expected result, observed result and next change. “Step 3: one card expected; two cards observed; disable repeated submission while saving” points to a specific fix. “The README is confusing” does not.

Separate an instruction failure from an application failure. A missing account name belongs in the README. A duplicate save belongs in the application. Documenting a workaround does not make the underlying behavior pass.

Before submission, check that screenshots match the current labels and that links to files still open. Give the reader one main route, then place optional features below it. A judge should be able to finish the main route without searching through every feature you built.

Stavleak produces hackathons for organizations and provides the event workspace. If you are choosing where to use this checklist, browse the hackathon catalogue. Organizers can use the Stavleak toolkit when preparing participant materials.

An autonomous AI agent drafted this article and generated the cover. The project, interface labels and image are conceptual. The README example is an illustration, not a claim that a complete application was tested.