All posts

Tools

Write a hackathon README that helps judges try your project

Make your project easy to understand and run. Use a short overview, a reliable demo path, sample inputs and an honest account of what works.

HackHoster Team · · 5 min read

Illustrated calendar, checklist and document connected into a workflow
Illustration: HackHoster (AI-assisted), original artwork

At a glance

  • Put the working demo and a short explanation near the top of the README.
  • Test setup instructions from a fresh checkout before submitting.
  • Explain sample data, third-party services and any simulated steps.
  • Document limitations and give credit to the tools and work you reused.

Practical guidance from HackHoster. Sources and illustration credits accompany the article. Publishing standards and corrections.

A hackathon README should let a new person understand the problem, open the demo and reproduce the main result without asking you for help. Start with the useful outcome, then provide the shortest dependable route to trying it. A clear README makes your working project easier to evaluate.

This guide is a suggested structure from the HackHoster Team. It does not replace the monthly challenge rules. Read those for the exact submission requirements, and include any additional information the challenge requests. Keep the documentation close to the version of the project you actually submit.

A laptop and notebook ready for a small software project
Illustration: HackHoster (AI-assisted), original artwork

Explain the project in one short paragraph

Name the intended user and the task before listing the technology. For example: “Meeting Basket helps student clubs turn meeting notes into an editable action list. Paste a sample transcript, review the suggested tasks and export a checklist.” That gives a reader a concrete picture of what they can do.

Then explain the constraint your team chose. Maybe the prototype handles plain text and English only, or it works with a supplied dataset. These boundaries help a reviewer choose a sensible test. They also prevent a small working prototype from being mistaken for a finished commercial service.

Avoid opening with a wall of badges or a long story about your team. The reader needs to find the project and its purpose first. You can include the team, architecture and development notes after the basic route to the demo is clear.

Put the demo path near the top

Provide a clearly named live-demo link and a separate walkthrough link if the challenge asks for one. Add the expected time to complete the sample task. Tell the reader whether an account is required and whether the demo can be reset. Use a dedicated sample account only when it is appropriate to share it publicly.

Give one concrete input and the result the reader should expect. For a text tool, include a short sample they can paste. For a dashboard, provide a sample file. For an interactive project, describe the first action to take and how to recognize success. Do not make a reviewer invent the data needed to discover the main feature.

If a service is temporarily unavailable, show a useful message and explain which parts still work. A recording can illustrate behavior, but it should not conceal that the live version is incomplete. Label prerecorded, simulated or manually prepared results so the demo tells an accurate story.

Make setup instructions reproducible

Start from a clean checkout and follow your own instructions. Write the runtime and package manager versions, installation command, configuration file names and run command. Provide an example environment file containing variable names and harmless placeholders. Keep actual credentials out of the repository and screenshots.

Explain how to load sample data, what address to open and how to stop the app. If an external provider is required, link to its official setup documentation and describe the needed capability. Do not assume the person reviewing your submission has access to your personal dashboard or paid account.

GitHub’s README documentation describes a README as a place to explain what a project does and how to use it. For a hackathon, make that promise concrete by checking every command against the submitted revision rather than the older version on your laptop.

Ask a teammate to follow the README in a new folder. Every question they ask is a possible missing step in the instructions.

Show how the important pieces fit

Describe the flow of data in a short paragraph or a small diagram. Identify where input comes from, where your code processes it and where a result is stored. If the project uses a model API, explain what that API receives and what your own application adds around the response.

Separate your contribution from reused components. List frameworks, starter templates, datasets, models and libraries with links. Explain substantial changes you made. This gives the reviewer a clearer picture of the work than an unqualified claim that the team built everything from scratch.

Include a short note about data handling. State whether the demo uses synthetic data, stores uploads or sends input to another service. Keep the statement specific to the prototype. If you have not checked a provider’s retention behavior, do not claim that all data disappears immediately after a request.

Document checks and limitations

List the small set of checks that matter to the core workflow. A task extractor might have examples for a normal meeting, ambiguous ownership, no action items and a service timeout. Explain whether these checks are automated, manual or both. Link to relevant test files when they exist.

Keep the limitations useful. “The prototype currently supports text files under a fixed size” is more informative than “there may be bugs.” Say what happens beyond the boundary and what a user can do instead. If generated answers can be wrong, show how the interface encourages review before a result is used.

Describe one or two next steps that follow from what you learned. A focused improvement, such as validating task owners against a supplied member list, is easier to assess than a promise to add every possible integration. Avoid presenting future plans as already working features.

Credit people and clarify reuse

List teammates and their contributions without inventing roles or achievements. Add attribution for artwork, data and borrowed code where required. Link to the licenses of dependencies or assets when that helps someone understand reuse conditions. Keep consent and private contact information in mind when sharing team details publicly.

A public repository and an open-source license are different decisions. GitHub provides licensing guidance for understanding how a license communicates reuse permissions. Choose deliberately and include the applicable license file rather than assuming that a public link answers every question.

Check the final version before submitting

Open the README on its public repository page. Follow the demo, video and source links as a signed-out reader. Confirm images load, relative links resolve and the documented sample still produces the expected result. Remove obsolete instructions and claims that no longer match the app.

Then use the demo testing checklist and review the current challenge. Submit the project through the required workflow and verify its submitted status. Documentation is part of the experience a judge receives, so give it the same attention as the first screen of the app.

Sources