Submission
Write READMEs, record demos, and submit deliverables that make judges remember you.
The Submission Advantage
Your submission is the artifact that outlives your pitch. Judges deliberate without you — your Devpost, README, and demo video speak on your behalf.
Most teams treat the submission as an afterthought, something to rush through in the last 30 minutes. Winning teams treat it as a first-class deliverable. Your Devpost README, GitHub repo, and demo video are what judges reference during deliberation. If they can't remember your project, your submission is the tiebreaker.
The narrative that frames your project for every judge, including those who never saw your live demo. This is the document most judges read during deliberation. It needs to tell the full story: problem, solution, tech, and vision.
Most hackathon winners allocate 1-2 hours specifically for writing this. It's not an afterthought.
The technical credibility signal that proves you built something real. Technical judges will click your repo link. Clean code, good structure, and a proper README with architecture diagrams separate serious teams from weekend projects.
The GitHub README is for developers. The Devpost is for everyone. Write both.
The visual proof that persists into deliberation. When judges forget your project (which happens more than you'd expect), your demo video is the reminder. Nothing beats seeing the product actually work.
Devpost calls the demo video one of the most important elements of your submission.
Tom Preston-Werner — GitHub Co-founder
“Until you've written about your software, you have no idea what you'll be coding.”
Writing the README forces you to understand what you actually built. The act of documenting is the act of clarifying: for yourself and for judges.
The Devpost README — Section by Section
Every Devpost submission follows the same template. Here's how to write each section so judges remember your project during deliberation.
Inspiration
Lead with a striking stat or scenario that makes judges feel the problem. "82% of emergency call centers are understaffed." "Over 5 million children are hospitalized every year." "1.7 billion adults worldwide remain unbanked." Make them care before you describe your solution.
Avoid vague openers like "We wanted to help people." Concrete numbers and vivid scenarios stick in judges' minds during deliberation.
What It Does
2-3 sentences max, then bullet the key features. Be concrete and specific: "Users check balances, transfer funds, and pay bills using voice commands" beats "An AI-powered banking solution."
Name the user. Name the action. Name the outcome. Judges should be able to repeat your pitch to another judge from this section alone.
How We Built It
Architecture diagram first, then a bullet list naming every API, framework, and service. Include a system design image; one visual explains what 500 words cannot. Group by Frontend, Backend, AI/ML, and Infrastructure.
Name-drop sponsor technologies prominently. If you used Intel Dev Cloud, Hume, Retell, or any sponsor API, make it impossible to miss.
Challenges We Ran Into
Be honest. "Integrating multiple APIs seamlessly" and "Fine-tuning the model to handle edge cases" are relatable. Saying "We didn't have any challenges" is a red flag that suggests you didn't push hard enough.
Challenges show maturity. Judges want to see that you faced real problems and solved them, not that everything went perfectly.
Accomplishments
What went right. Tie accomplishments back to the original problem: "Successfully fine-tuned Mistral for emergency response scenarios" connects to the 82% understaffing stat. Make the loop from problem to proof.
Include quantitative wins: "80% decrease in processing time," "multi-language support in 6 languages," "functional prototype in 18 hours."
What We Learned
Growth signal. Judges want to see you're reflective, not just productive. "How to design multidimensional agentic systems" and "The importance of multi-layered security" show depth of understanding beyond the code.
This section is especially important for educational and "best beginner" tracks. It proves the hackathon taught you something.
What's Next
Future vision that shows the idea has legs beyond the weekend. "Expand training data," "Partner with local emergency services for real-world testing," "Mobile app integration." Show judges this isn't a throwaway project.
2-4 concrete next steps. Avoid pie-in-the-sky claims; judges can tell the difference between ambition and delusion.
The GitHub README — Structure for Credibility
Technical judges will click your repo link. A clean GitHub README with architecture diagrams and install instructions separates serious teams from weekend projects.
- Project title + one-line description
- Prize/award badge at the top (shields.io)
- Demo video or hero screenshot
- Tech stack badges (React, TypeScript, Tailwind, etc.)
- Architecture diagram
- Getting started / installation steps
- Key features list
Non-negotiable
these make or break technical credibility
bonus points
bonus points
- Contributing guide
- Detailed API documentation
- Environment variable reference
- Deployment instructions
- License file
Extra credit
separates good from great
Remember: The GitHub README is for developers and technical judges. The Devpost is for everyone. They serve different audiences; write both, and tailor each to its reader.
Why This Works — The Science of Great Documentation
The best hackathon submissions follow the same principles that make great journalism, great memos, and great products memorable.
Journalism's most fundamental structure: put the most important information first. Judges skim, so your opening line determines whether they keep reading or move on to the next project.
Lead with impact, not backstory. “82% of call centers are understaffed” hooks instantly. “We're a team of four students who…” does not.
“The narrative structure of a good memo forces better thought and better understanding of what's more important than what.”
Bezos banned PowerPoint at Amazon in favor of structured narrative memos. The same principle applies to your Devpost: writing a coherent story forces you to understand what you actually built and why it matters.
“If it is possible to cut a word out, always cut it out.”
Orwell's 1946 rules for clear prose apply perfectly to hackathon submissions: never use a long word where a short one will do, never use the passive where you can use the active, and break any of these rules sooner than say anything barbarous.
Show the essential information first, then let readers drill deeper if they want. Stripe's documentation, widely regarded as the gold standard, follows this principle: quickstart at the top, architecture details further down.
Apply to your README: hero screenshot and one-liner first. Architecture and install instructions for those who want depth.
Show, Don't Tell
A screenshot is worth a thousand words. An architecture diagram is worth a thousand meetings. A demo video is worth a thousand Devpost entries.
“Don't tell me the moon is shining; show me the glint of light on broken glass.”
— Anton Chekhov, letter to his brother, 1886
Chekhov's principle for fiction applies perfectly to hackathon submissions. Don't describe your app; show it. Don't explain your architecture; diagram it. Don't claim it works; record it working.
One system design image explains what 500 words of “How We Built It” text cannot. Show the flow: user action → frontend → API → AI model → response. Use Excalidraw, Figma, or even a whiteboard photo.
Every winning Devpost in the examples above included an architecture diagram. It's not optional.
4-6 annotated screenshots of key flows. Not raw screen captures; add callouts, arrows, and labels that guide the reader through the experience. The DoggoAI submission included design process images that dramatically elevated it.
Include: user personas, wireframes, high-fidelity mockups, and the final product side-by-side. Show the journey.
Recording Tools
Screen Studio (Mac) or CanVid (Windows). Auto-zoom, instant effects, webcam overlay. Minutes, not hours.
Video Length
60-90 seconds. Long enough to show the flow, short enough to hold attention. One take is fine; authenticity beats polish.
Screenshot Count
4-6 annotated images. Hero shot, architecture diagram, 2-3 key flow screenshots, and one design process image.
Common Mistakes
These six submission mistakes kill otherwise strong projects. Avoid them and you're already ahead of 80% of teams.
No Demo Video
Instant disadvantage. Judges can't remember what they can't see. A 60-second recording is the highest-ROI activity of your hackathon.
Wall of Text
Nobody reads a 2000-word README with no images. Break it up with screenshots, diagrams, and headers. If a judge has to scroll to find the point, you've lost them.
Vague Inspiration
"We wanted to help people" vs "82% of call centers are understaffed." The second makes judges care. The first makes them yawn.
Missing Tech Details
Judges, especially sponsor judges, want to know HOW you built it, not just WHAT. Name every API, framework, and service. Include the architecture diagram.
No Architecture Diagram
Makes the project feel unplanned and thrown together. One Excalidraw diagram takes 15 minutes and completely changes the perception of technical depth.
Late Submission
Devpost deadlines are hard cutoffs. Submit 30 minutes early. Teams lose every hackathon because they hit "submit" at 11:59 and Devpost lagged.
“The narrative structure of a good memo forces better thought and better understanding of what's more important than what.”
— Jeff Bezos, Amazon shareholder letter, 2017
Your submission isn't an afterthought; it's the document that represents your project when you're not in the room. The teams that write great Devpost READMEs aren't adding fluff. They're forcing themselves to understand what they actually built, why it matters, and how to make someone else care.
Every section of your submission is an act of clarity. The Inspiration section forces you to articulate the problem. The “How We Built It” section forces you to understand your own architecture. The “What's Next” section forces you to think beyond the weekend.
The best submission doesn't describe the project; it makes the reader wish they had built it.
Submission Checklist
A step-by-step summary for crafting your submission. Allocate 1-2 hours before the deadline — this is not optional.
Write the Devpost README BEFORE the hackathon ends. Allocate 1-2 dedicated hours.
Lead Inspiration with a striking stat or scenario, not "we wanted to help people"
Include an architecture diagram and 4-6 annotated screenshots in the submission
Record a 60-90 second demo video with Screen Studio or CanVid, with webcam overlay for personality
Write a separate GitHub README with tech badges, install instructions, and the architecture diagram
Name-drop every sponsor technology prominently in "How We Built It"; make it impossible to miss
Submit to Devpost 30 minutes before the deadline; never cut it close
Proofread once for Orwell: cut every word that doesn't earn its place
Remember: Judges deliberate without you in the room. Your Devpost README, demo video, and GitHub repo are your advocates. Make them count. They're the difference between “I think that project was good” and “I remember exactly why we should pick that one.”
AI Prompt Templates
Copy these prompts into Claude, ChatGPT, or any AI tool along with your project details. They're designed to generate submission-ready READMEs that follow every principle on this page.
What to Paste Along With the Prompt
You are a hackathon submission expert. Generate a Devpost README for my hackathon project using the information I provide below.
Follow these rules strictly:
INSPIRATION SECTION:
- Open with a striking statistic, vivid scenario, or concrete number that makes the reader feel the problem BEFORE describing any solution
- Use bold markdown for key stats (e.g., **82% of call centers are understaffed**)
- Do NOT start with "We wanted to..." or "Our team decided to..." — lead with the problem, not yourself
- 2-3 short paragraphs maximum. Make every sentence earn its place.
WHAT IT DOES SECTION:
- Start with 2-3 sentences summarizing the product from the user's perspective
- Then list 3-5 key features as bullet points with bold titles
- Be concrete and specific: "Users check balances, transfer funds, and pay bills using voice commands" NOT "An AI-powered solution"
- If relevant, mention the core user flow
HOW WE BUILT IT SECTION:
- Group technologies by category: Frontend, Backend, AI/ML, Infrastructure, APIs
- Name EVERY API, framework, library, and service used — especially sponsor technologies
- Describe the architecture briefly (e.g., "User speaks → Twilio captures audio → GPT-4 processes → response streamed back")
- If there's a system design or architecture image, reference it with 
- Mention any custom datasets, fine-tuned models, or novel technical approaches
CHALLENGES WE RAN INTO SECTION:
- List 3-5 real, specific challenges — NOT generic ones
- Be honest. "Integrating multiple real-time APIs with different auth patterns" is good. "Time management" is lazy.
- Briefly mention how you overcame each challenge or what you learned from it
ACCOMPLISHMENTS THAT WE'RE PROUD OF SECTION:
- Tie accomplishments back to the original problem statement
- Include quantitative results where possible (e.g., "80% reduction in inference time", "supports 6 languages")
- Mention any technical firsts or novel approaches
WHAT WE LEARNED SECTION:
- Focus on genuine technical and personal growth
- Be specific: "How to orchestrate multi-agent LLM systems" NOT "We learned a lot about AI"
- 3-5 bullet points
WHAT'S NEXT SECTION:
- 3-5 concrete, realistic next steps
- Mix short-term (next month) and medium-term (next year) goals
- Show the idea has legs beyond the hackathon without being delusional
GENERAL RULES:
- Use markdown formatting: bold for emphasis, bullet points for lists, headers for sections
- Follow the inverted pyramid: most important information first in every section
- Apply Orwell's rule: if a word can be cut without losing meaning, cut it
- Write in first person plural ("we") with energy and confidence
- Total length: 800-1500 words. Comprehensive but not bloated.
---
HERE IS MY PROJECT INFORMATION (replace this section with your actual details):
Project Name: [YOUR PROJECT NAME]
Hackathon: [HACKATHON NAME]
Problem/Inspiration: [Describe the problem you're solving and why it matters]
What it does: [Describe what your project does from the user's perspective]
Tech stack: [List all technologies, APIs, frameworks, and services used]
Sponsor technologies: [List any sponsor APIs or tools you used — these are critical]
Challenges: [List the main challenges you faced]
Accomplishments: [What went well? Any metrics or quantitative results?]
What you learned: [Genuine learnings — technical and personal]
What's next: [Future plans for the project]
Additional context: [Any other details — team background, special features, design process, etc.]What to Paste Along With the Prompt
You are a developer documentation expert. Generate a polished GitHub README.md for my hackathon project using the information I provide below. Follow these rules strictly: STRUCTURE (in this exact order): 1. PROJECT TITLE AND BADGES - Start with: # ProjectName - If a prize was won, add a line like: ### 🏅 [Hackathon Name] - [Prize Won] - Add a centered block of shields.io tech stack badges using this format: <img src="https://img.shields.io/badge/[TECH]-[COLOR]?style=for-the-badge&logo=[LOGO]&logoColor=white" alt="[TECH]"> - Group badges by "Frontend built with:" and "Backend built with:" with <br> tags - Use the for-the-badge style for all badges 2. HERO SECTION - Add a centered screenshot or demo video placeholder: <p align="center"><img width="1728" alt="Screenshot" src="YOUR_SCREENSHOT_URL"></p> - Below it, write 2-3 sentences describing the project's purpose and impact - Include a key statistic or problem statement in bold 3. WHAT IT DOES - 2-3 sentence overview - Bullet list of key features with bold titles 4. ARCHITECTURE / HOW WE BUILT IT - Reference an architecture diagram:  - List the tech stack organized by category (Frontend, Backend, AI/ML, Infrastructure) - For each technology, briefly explain WHY it was chosen and what role it plays - Name every API and service 5. GETTING STARTED - Prerequisites section with required tools/versions - Step-by-step installation: ```bash git clone https://github.com/username/repo.git cd repo npm install # or pip install -r requirements.txt ``` - Environment variables section: ```bash cp .env.example .env # Fill in your API keys ``` - How to run: ```bash npm run dev ``` 6. KEY FEATURES (if not covered above) - Detailed feature descriptions with sub-bullets if needed 7. CHALLENGES AND LEARNINGS - Brief section on technical challenges overcome - Key learnings from the project 8. WHAT'S NEXT - 3-5 concrete future plans 9. TEAM / CONTRIBUTORS - List team members with their roles and GitHub links - Format: **Name** - Role - [@github](https://github.com/username) 10. LICENSE - MIT License (or as specified) GENERAL RULES: - Use clean, consistent markdown formatting - Code blocks should specify the language (bash, typescript, python, etc.) - Keep descriptions concise — this README is for developers and technical judges - Use shields.io badges for ALL technologies in the tech stack - Include placeholder comments like <!-- Add screenshot here --> where images should go - Write in a professional but energetic tone - The README should make someone want to clone the repo and try it --- HERE IS MY PROJECT INFORMATION (replace this section with your actual details): Project Name: [YOUR PROJECT NAME] One-line Description: [One sentence describing what it does] Hackathon: [HACKATHON NAME] Prize Won: [Prize name, or "N/A"] Tech Stack - Frontend: [e.g., Next.js, React, TypeScript, Tailwind CSS, shadcn/ui] Tech Stack - Backend: [e.g., Python, FastAPI, Node.js] Tech Stack - AI/ML: [e.g., GPT-4, Whisper, custom fine-tuned model] Tech Stack - Infrastructure: [e.g., Vercel, Supabase, Firebase, AWS] APIs Used: [e.g., Twilio, Hume, Retell, Google Maps] Key Features: [List 3-5 main features] Install Steps: [How to set up and run the project locally] Environment Variables Needed: [List required env vars like OPENAI_API_KEY, etc.] Team Members: [Names, roles, and GitHub usernames] License: [MIT / Apache 2.0 / etc.] Additional Context: [Architecture details, special setup, hardware requirements, etc.]
Pro tip: These prompts work best when you give them raw, detailed input, even messy bullet points. The AI will structure it. After generating, proofread with Orwell's rule: cut every word that doesn't earn its place.