docs/portfolio-writeup-outline.md is ready for you to customize for your full-stack capstone project. Most portfolio writeups go 80% finished and get abandoned, because creators get stuck deciding what to include, ramble through irrelevant tool lists, or fail to tie their work to tangible problems. A 2024 survey of technical recruiters found 72% of project writeups get skipped entirely, because they do not answer the core question every reader asks: why does this project exist, and why did you build it the way you did? This outline removes decision fatigue, cuts total writeup time to under an hour, and gives you a structured end product that holds a reader’s attention from start to finish.
Frame the core user problem
Your opening section exists to hook the reader before they disengage, so you lead with the specific user and pain point your project solves, not the tools you used to build it. Skip generic claims like “I built this to practice React” — tie the work to a real, measurable gap that impacts the people you built it for. Readers care far more about who benefits from your work than what dependencies you installed.
Illustrative example: if your project is a local bakery inventory tracker, your problem statement does not lead with “I built this with React and Prisma” — it leads with “Small bakery owners in my area tracked ingredient stock in shared spreadsheets that crashed 3x per week during weekend prep, leading to $1,200 average monthly waste from over-ordered perishables.” This framing immediately gives context for every choice you made later in the build, and gives recruiters a clear sense of how you apply technical skills to solve real-world problems. You only include details that are relevant to the pain point, and end this section with a 1-sentence summary of what your project does to fix the gap you described.
List non-negotiable project constraints
Constraints make your technical decisions make sense to outside readers, and demonstrate you can make intentional tradeoffs under pressure — a core skill for any development role. Without clear constraints, readers will question why you chose a simpler tool over a more complex alternative, or why you cut a feature that seems obvious in hindsight. You stick to 3 to 4 concrete, verifiable constraints, no vague claims like “I had limited time.” Examples of valid constraints include a 3-week build window for a bootcamp capstone, a requirement to use only free-tier hosting and no paid API keys, a mandate for WCAG 2.1 AA compliance for users with visual impairments, or a rule that core functionality works offline for users with spotty internet access. You tie each constraint directly to a decision you made later in the build, so readers can follow your logic without asking follow-up questions.
Map the base file line structure
This outline pre-defines every section of your writeup, with clear prompts and word count ranges to eliminate writer’s block. You delete placeholder comments as you fill in each section, so you never stare at a blank page while drafting. This structure aligns with the portfolio best practices shared across Build Next Stack full-stack project guides, and is optimized for both scannability for recruiters and depth for technical interviewers.
| Line number | Section title | Required content notes | Word count range |
|---|---|---|---|
| 1 | Frontmatter header | Project name, live demo link, public GitHub repo link, 3 to 4 core tech stack bullet points | 50 – 75 |
| 10 | Core problem statement | Exact user group you served, specific pain point you addressed, measurable metric of that pain point if available | 100 – 150 |
| 22 | Project constraints | 3 to 4 non-negotiable limits that shaped every build choice, with brief context for each constraint | 75 – 125 |
| 32 | Key decision log | 3 to 4 high-impact technical or design choices you made, with justification tied directly to your stated constraints | 200 – 300 |
| 48 | Interactive demo walkthrough | Step-by-step breakdown of your core user flow, with embedded screenshots or timestamp markers for any linked video demo | 150 – 250 |
| 68 | Leftover work and improvements | 2 to 3 features you did not complete during the initial build, or changes you would make if you rebuilt the project from scratch | 100 – 200 |
Each section builds on the last, so readers get a complete narrative of your project without tangents or irrelevant details. You do not add extra sections unless they directly support the core narrative, and you stick to the word count ranges to avoid rambling.
Add interactive demo context
A generic Loom link or live demo URL is not enough to hold a reader’s attention, because most people will not take 10 minutes to click through your unsupervised project. Instead, you frame your demo around the same core user flow you referenced in your problem statement, so readers see exactly how your tool solves the pain point you opened with. For the bakery inventory example, you walk through three specific steps: first, the bakery owner logs in with their existing Google account, no separate password required per user feedback collected during initial interviews; second, they input their daily leftover ingredient counts, and the tool automatically adjusts the next week’s order quantities to match historical usage patterns; third, they export the finalized order to their supplier’s email with one click, no manual copy-pasting required. You add one small, cropped screenshot for each step, so readers can follow the flow without clicking away from the writeup, and add 1-sentence context for each step that ties it back to your original constraints or user needs. You include one quantitative outcome of the project if available, such as a 32% reduction in ingredient waste for the bakery that tested your tool, to prove your work delivers tangible value.
Next time you open docs/portfolio-writeup-outline.md
You start with the easiest section first to build momentum: the frontmatter header. You copy over your repo link, live demo link, and list the 3 to 4 core tools you used for the build, no need to list every minor npm package or utility library. Next, you paste the rough problem statement you jotted down when you first pitched the project, and tweak it to include the measurable pain point metric you collected from user interviews or initial research. Then you fill in the constraints section, pulling directly from your project planning notes to ensure each constraint is specific and verifiable.
From there, you move to the key decision log, listing the biggest choices you made during the build and tying each one to a constraint you already listed: for example, you chose Prisma over raw SQL because you only had one week to build your backend and Prisma’s built-in query validation cut down on debugging time, or you chose Tailwind over custom CSS because you needed to prioritize mobile responsiveness for bakery owners who access the tool on their phones during prep shifts. You then add your three demo screenshots and any relevant timestamps for your video walkthrough, writing the 1-sentence context for each step to tie it back to your core user flow. Finally, you fill in the leftover work section, listing features you did not have time to build, bugs you did not get to fix, or changes you would make to your tech stack if you rebuilt the project today.
You do not need to make the writeup perfect on the first pass. You only need to fill every section, and you can tweak wording or add extra details later as you get feedback from peers or interviewers. The end result is a concise, narrative-driven writeup that readers make it all the way through, with no unfinished sections or abandoned drafts left cluttering your project repo.