A README for the judges: prepare a hackathon demo they can check
Build your submission around one scenario: a specific input and result, tested commands, safe data, judge access and a fixed commit.
·7 min read
What you’ll learn
Describe one scenario with an exact input and expected result.
Test the instructions at a fixed commit without spoken hints.
Distinguish working features, stubs and access limitations.
Before submitting your project, check whether someone outside the team can get the same result. An accessible repository link does not establish that. Your README needs specific data, steps and observable signs of success. They help a judge distinguish a setup failure from a product error and ask about what actually works.
Build the document around a scenario you are ready to repeat. Below, we use an illustrative room filter based on equipment. The identifiers and data are fictional; this is not a description of a real event or rooms. The same process works for another prototype when you replace the input, result and setup requirements.
1. Show one complete task
Start with the user action: “Select rooms with a projector and a whiteboard.” Then name the result: a list of matching identifiers. In the sample dataset, demo-room-a has projector and whiteboard, while demo-room-b has only projector. The input {"required":["projector","whiteboard"]} should return {"rooms":["demo-room-a"]}.
Write down where a person enters the request and where they see the answer. For an interface, give the screen and control names; for an API, give the specific route, method and request body. The example above shows request content, not a ready-to-use service address. Insert only a route you have implemented.
Define how to compare results: whether room order matters, whether additional fields are allowed and what happens when nothing matches. If the prototype shows a list, check the list rather than just the absence of an error. For our data, the request {"required":["microphone"]} expects {"rooms":[]}. This second sample input helps check the no-match behavior.
2. Connect the README to the submitted version
State the project's condition at the beginning: the working prototype, tested scenario and unfinished parts. GitHub describes a README as a place to understand a project's purpose, how to get started and where to get help. For a submission, add a link to the code version being reviewed.
Update the README before the final commit. After creating that commit, copy its full identifier into the submission form and the demo check record. Record the identifier of the commit containing the README after creating it: saving that identifier in the file itself would require another commit. Do not label the main branch as an immutable version.
To link to a specific file, open it on GitHub and press Y: the permalink will point to the file version in a commit. Separately explain which code runs the hosted demo. If the local version and server differ, do not leave the judge to discover this from the screen's behavior.
3. Take the reader from a clean copy to an answer
Choose a primary route: a local run or an accessible hosted demo. Before the steps, list the runtime and dependency manager versions you actually checked, along with required external services. “Latest” does not preserve the conditions in which you tested the project.
For a local route, record the working directory, installation using the saved dependency lockfile, configuration setup, test data loading and startup. Give an observable result after each step: the configuration file appears, the sample rooms load or the required screen opens. Use commands from your repository and test them in the stated order. Generic installation instructions may omit your migration or file generation step.
Explain settings by name. For example, APP_MODE selects demo mode and DEMO_DATA_PATH points to the sample data, if your project implements these settings. For each one, state whether it is required and where it is used. If an integration needs SERVICE_API_KEY, give its name and the agreed way to obtain test access, without placing the key value in the README. Do not add variables the application does not read.
4. Prepare data and a repeat run
Put a safe input in an accessible file and connect it to the expected answer. Our example needs only a sample room list with the two identifiers and their equipment. The filename and location must match the instructions. A reader should not have to reconstruct the dataset from a screenshot.
Explain how to reset state: which demo records are removed, what is loaded again and how to confirm that the starting conditions have been restored. Restrict the reset to test data. If the prototype changes state, repeat the scenario after resetting it and save the observed result.
Check that files and screen recordings contain no real contact details, work documents, tokens or access to someone else's systems. For another team's code, use a disposable isolated environment without work secrets or host-folder mounts. These conditions match the submission acceptance checklist.
5. Name dependencies and demo limitations
Distinguish what runs in code, what is shown as a stub and what is not implemented. Our illustrative filter checks equipment in a dataset. It does not establish that a room exists in a real building, is available at a given time or can be booked. Put these limitations beside the promised result.
If an external service is required, describe the dependency, test access and observed behavior when it is unavailable. A backup recording shows the recorded scenario; it does not confirm behavior on a new request. Label demo mode as demo mode, without claiming a working integration.
For an AI prototype, save the versions of available components, the prompt, raw response and run settings. One successful example does not establish quality on other data. The AI demo evaluation guide covers the held-out evaluation process in detail. Do not promise a repeatable result if the external service's conditions cannot be pinned.
6. Check the judge's actual permissions
Open the code, demo, data and recording with the permissions the reviewer will receive. Opening them from the owner's account does not establish judge access. Record whether an invitation is needed and when test access expires. For a private repository, use the agreed method for sharing material.
GitHub lets repository administrators manage access for people and teams. Check the invitation and required permissions separately from whether the application works. Do not publish restricted material to make a link convenient. Share login details through an approved channel and leave instructions for obtaining them in the README.
7. Connect evidence to the judging criteria
Take the published judging criteria and point to something verifiable for each criterion relevant to your work: a scenario, file, result or explanation. Do not award yourself points or claim product readiness based on a single run.
Describe your work and starting components to the extent required by the hackathon rules: existing code, assistance, libraries and AI use. “Everything is ours” does not explain the boundaries of your contribution. A file link and a description of the change give a judge something specific to ask about.
8. Rehearse without hints
Ask a teammate to follow the document from beginning to result in a clean environment. Record where they stop and what help they need. If you manually create a hidden configuration file or change the data, that is part of the scenario that needs to be documented and repeated.
Save a short record: checked commit, environment, input, steps, expected and observed result, blocked step, author assistance and limitations. The Stavleak acceptance kit helps record the check; its validator checks the record's structure, while a person checks access and scenario execution.
Before submitting, fix differences between the README, files and project form. Keep the document version with the code and check the links again. In the pitch, you can then point to a specific tested scenario, explain the remaining limitations and let a judge repeat your work.
