All posts

Tools

Explain your project with a clear problem, evidence and limits

Write a submission story that connects the monthly theme to the work you actually built and the checks you actually ran.

HackHoster Team · · 4 min read

Modular ivory prototype pieces and a notebook on a matte charcoal workbench
Illustration: HackHoster (AI-assisted), original artwork

At a glance

  • Name a specific audience, task and useful result in the opening.
  • Connect implementation decisions to what a person can do.
  • Separate completed behavior from future plans and prepared examples.
  • Use observed evidence, accurate credits and a practical limitation.

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

A strong project explanation helps a reviewer understand the problem, try the result and judge the contribution. Write about the work you completed rather than the company you might build around it someday. Clear evidence and accurate limits make a small prototype easier to assess than a large promise supported only by a polished description.

Use this structure for the walkthrough in your HackHoster submission, then adapt it to the exact fields in the Submission tab. It is a writing framework, not a recipe that guarantees a prize. The published judging criteria describe how eligible entries are reviewed for the current challenge.

Conceptual illustration of building a focused prototype from small components
Illustration: HackHoster (AI-assisted), original artwork

Open with a person and a useful change

Write one sentence naming who the project is for, what they need to do and the result it provides. For an imaginary tool, that could be a club organizer turning meeting notes into a reviewed checklist. Avoid opening with a list of frameworks or a general statement about how technology is changing the world.

Follow with a concrete example of the original difficulty. The organizer searches several documents and still misses an owner for a task. That scene gives the reader a way to understand why a review step matters. Keep the example honest: if it is fictional, describe it as an illustrative scenario rather than a customer story.

Explain the connection to the theme

Describe what part of the monthly theme the project addresses. For an information-to-action challenge, show how the tool transforms scattered input into a usable next step. The connection should be visible in the workflow. Adding the theme's keywords to an unrelated application does not explain a meaningful relationship.

Keep this section specific to your implementation. A statement that the project uses AI could apply to thousands of tools. Explain what input you accept, what processing happens and what the person can do with the result. If you deliberately narrowed the scope, give the reason and the benefit of that decision.

Walk through the actual version

Write the journey as steps someone can repeat with the supplied sample. Tell them where to open the project, what to enter and what a successful result looks like. Include access instructions through the appropriate submission field when needed. Do not assume the reviewer has your local development environment or your logged-in session.

Distinguish working features from simulations and prepared examples. If an external service is mocked, say what the mock represents and what remains unimplemented. If the application requires a particular data format, name it. These details help someone interpret the result without guessing which parts of the presentation are live.

A useful walkthrough lets another person reach the same outcome. It should explain more than what the interface looks like.

Make the contribution understandable

Choose a few implementation decisions that affected the outcome. Perhaps you separated uncertain suggestions from confirmed records, added a reviewable export or built a resettable sample mode. Explain why each choice helps the user. Technical detail earns its place when it clarifies a behavior or tradeoff the reviewer can inspect.

Credit the starting point and borrowed resources. Identify existing templates, libraries, models, datasets and assets, and explain what you built during the challenge. Using tools is part of building; the important distinction is whether the submission makes your contribution clear. Keep the attribution consistent between the project form, README and recording.

Report what you tested

Describe the checks you actually performed. You might have tested six fictional note samples, an empty input and an unavailable service, then asked a teammate to try the journey without help. Include the observed result and any remaining failure. Do not turn that small exercise into a claim that the project works for all users.

If you measured something, explain the method and sample. A percentage without a denominator or evaluation rule can mislead more than it informs. For AI output, a short rubric with examples is often more useful than a broad accuracy label. The evaluation guide describes a practical way to record that evidence.

End with a boundary and a next step

Name a limitation that matters to someone trying the application. It may not handle scanned text, resolve ambiguous dates or support concurrent edits. Explain the consequence in plain language. Then identify one next improvement grounded in what you learned, rather than adding a long wish list unrelated to the demonstrated task.

Before submitting, compare the story with the actual demo and repository. Check that the title, links, sample and credits describe the same version. Remove claims you cannot support and vague sentences that do not help someone use or assess the project. The result should leave a reviewer with a clear view of what you made, why it helps and where it stops.

A short exercise to try

Ask a teammate to read the draft and answer three questions: who is this for, what can it do today and how would I check the claim? Do not answer for them while they read. Their response reveals where the explanation relies on your background knowledge. Replace vague passages with the missing action, example or boundary, then check the links again. Keep the final story concise enough that a reviewer can understand the project before deciding which technical details deserve a closer look.

Sources