A portfolio is one way to make skills and decisions inspectable, especially when professional work is confidential or experience is limited. It does not replace a résumé, interview performance, references, or the criteria of a particular employer.
This guide covers 21 questions about choosing role-relevant projects, documenting authorship and trade-offs, providing a safe evaluation path, and maintaining a useful GitHub profile. Treat every recommendation as a way to present truthful evidence, not a guarantee of interviews.
Table of Contents
- Portfolio Project Questions
- Project Ideas by Role
- Documentation Questions
- GitHub Profile Questions
- Common Mistakes Questions
- Portfolio Strategy Questions
- Quick Reference
Portfolio Project Questions
A reviewer may spend little time initially deciding whether a project is relevant and evaluable. Make the problem, your contribution, the evidence, and the fastest safe evaluation path obvious.
What makes a portfolio project impressive?
An effective project demonstrates capabilities named in the target role. Solving a real problem can provide convincing constraints and feedback, but a well-designed simulation, course project, or open-source contribution can also work when authorship is clear.
Examples of real problem solving:
- A Chrome extension that automates something you do repeatedly
- A CLI tool that simplifies your workflow
- An app that tracks something specific to your life or hobby
For any project, document the starting point, users or assumptions, constraints, decisions, rejected alternatives, and what you personally implemented. Originality cannot compensate for broken code or unclear ownership; a tutorial-derived project can become useful evidence if the extension is substantial and honestly attributed.
What do interviewers look for in portfolio code?
A public repository makes code available, but not every reviewer will inspect it. Help a technical reader find representative code and verification quickly.
What they check:
- Consistent formatting and naming conventions
- Logical file organization
- Appropriate use of comments (explain why, not what)
- No obvious security issues or anti-patterns
- Tests or other checks that support important claims
- Clear boundaries between your work, generated code, dependencies, and starter material
Do not claim production readiness unless you can support it. A candid limitations section often demonstrates better judgment than hiding unfinished or insecure behavior.
When does a portfolio project need a live demo?
A live demo reduces evaluation friction, but it is not mandatory or appropriate for every project. A CLI, library, infrastructure project, paid integration, or security-sensitive backend may be better shown through a short recording, screenshots, generated documentation, a sandbox, or reproducible local steps.
Include in your README:
- Live demo link (prominent, at the top)
- Demo credentials or seeded data only when they are safe and isolated
- Screenshots, captioned video, or terminal transcript when a live demo is impractical
- Current status, prerequisites, limitations, and teardown instructions
Never publish production secrets, personal data, copied customer data, or an unrestricted costly API. Use synthetic data, budgets, rate limits, and least-privilege demo credentials, and verify the hosting provider's current terms before choosing it.
How important is commit history in portfolio projects?
An incremental history can show how work evolved, but a single import or squashed history is not proof of copying. Existing work may come from another forge, a private repository, or an intentionally squashed workflow.
Good commit history shows:
- Breaking work into logical chunks
- Addressing bugs and edge cases as you find them
- Iterating on features based on testing
Do not manufacture tiny commits or streaks. If history is unavailable, explain provenance in the README and use issues, pull requests, ADRs, release notes, or a short case study to show decisions.
Project Ideas by Role
Different roles need different demonstrations of skill. Build projects that match where you want to work.
What projects should frontend developers build?
| Evidence to show | Project shape | Example |
|---|---|---|
| Semantic, responsive UI | Content site or design system | Accessible documentation site with tested components |
| Client data and state | Interactive application | Dashboard with loading, empty, error, and stale states |
| Complex interaction | Collaborative or offline tool | Editor with explicit conflict and recovery behavior |
What frontend projects should demonstrate:
- Responsive design that works on mobile
- Accessibility evaluation (semantics, keyboard use, focus, text resize, contrast)
- State management for complex interactions
- Performance awareness (lazy loading, optimized images)
Project idea: Real-time Dashboard Build a dashboard from a documented public API or a local fixture. Include filtering, sorting, data visualization, loading/error/empty states, cancellation or stale-response handling, accessible chart alternatives, and a privacy-safe cache policy. Respect the source's terms and do not expose private API keys in browser code.
What projects should backend developers build?
| Evidence to show | Project shape | Example |
|---|---|---|
| HTTP and persistence | Small API | Resource API with validation and migrations |
| Identity and policy | Multi-user service | Roles or ownership with negative authorization tests |
| Reliability and operations | Production-shaped service | Idempotent job processing with metrics and recovery notes |
What backend projects should demonstrate:
- Proper API design (RESTful conventions or GraphQL schema)
- Authentication integration and server-side authorization
- Database design and relationships
- Error handling and validation
- Basic security practices
- Migrations, observability, failure handling, and operational documentation
Project idea: API with Rate Limiting and Caching Build an API around a permitted third-party sandbox or synthetic upstream. Add bounded timeouts, rate limiting, caching with explicit freshness, authentication through a maintained identity solution, resource-level authorization, and OpenAPI documentation. Show failure behavior and prevent secret, personal-data, and cost leakage. Do not add microservices merely to look senior; a coherent modular service is often easier to verify.
What projects should full-stack developers build?
| Evidence to show | Project shape | Example |
|---|---|---|
| End-to-end data flow | Small product workflow | Notes with ownership and validation |
| Concurrent state | Real-time or offline feature | Chat or editor with reconnect behavior |
| Product and operations | Multi-user workflow | Project tool with audit and recovery paths |
What full-stack projects should demonstrate:
- Frontend and backend working together seamlessly
- Identity lifecycle and server-side authorization, preferably through a maintained provider or library
- Data persistence and relationships
- Deployment of both frontend and backend
Project idea: Trello-lite A simplified project tool with boards, lists, and cards can demonstrate state management and data modeling. If you add drag-and-drop or real-time updates, include keyboard alternatives, reconnect/conflict behavior, authorization for every mutation, and observable failure states. Scope features to what you can test and explain rather than cloning an entire product.
Documentation Questions
Documentation makes a project faster to evaluate and distinguishes a maintained artifact from an unlabeled experiment.
What should a project README include?
A portfolio repository should usually have a README. Adapt this template to the artifact instead of adding empty sections:
# Project Name
One-line description of what it does.
## Status and Evaluation Path
Current project status, supported runtime, and the shortest safe way to evaluate it.
## Demo
[Live Demo](https://your-demo-url.com)
## The Problem
What problem does this solve? Why did you build it?
## The Solution
How does your project solve the problem? What approach did you take?
## Tech Stack
- Frontend: React, TypeScript, Tailwind
- Backend: Node.js, Express, PostgreSQL
- Deployment: static frontend host and managed application/database runtime
## Key Features
- Feature 1: Brief description
- Feature 2: Brief description
- Feature 3: Brief description
## Running Locally
Prerequisites, required environment-variable names, and synthetic seed data.
\`\`\`bash
git clone https://github.com/you/project
cd project
npm ci
npm run dev
\`\`\`
## Verification
Commands for tests, linting, type checks, and a production build.
## Security and Privacy
Threat assumptions, demo-account boundaries, vulnerability reporting, and data handling.
## Accessibility
Keyboard, screen-reader, zoom, contrast, and automated/manual checks performed.
## Limitations and Trade-offs
Known gaps, rejected alternatives, and what you would change for production.
## What I Learned
Briefly describe technical challenges you overcame or skills you developed.
## License and Attribution
License, starter material, generated assets, and other contributors.How do you create screenshots and GIFs for documentation?
Visual documentation makes your project accessible without running it.
What to capture:
- A representative user flow and important failure state
- Responsive behavior (desktop and mobile)
- Any unique features or animations
Use the capture tool available on your platform; the artifact matters more than the brand. Crop secrets and personal data. Give informative images useful alt text, caption videos, include a transcript when audio conveys information, avoid rapid or flashing motion, and keep equivalent instructions in text.
How do you document technical decisions?
Include a section explaining the constraints, alternatives, decision, consequences, and evidence. Avoid retrofitting a justification after the fact; label later reflection honestly.
## Technical Decisions
**Why PostgreSQL over MongoDB?**
The data has clear relationships (users have projects, projects have tasks).
A relational database made querying and maintaining data integrity easier.
**Why local reducer state instead of a shared store?**
The state belongs to one route and has no cross-route synchronization requirement.
A shared store would add another boundary without solving a measured problem.GitHub Profile Questions
If you share GitHub in an application, make the relevant evidence easy to find and understand. Do not assume every reviewer will use GitHub or can access private work.
How should you set up your GitHub profile README?
On GitHub.com, create a public repository named exactly after your username and put a non-empty README.md in its root. GitHub then displays it on the profile; this feature is not available to managed user accounts.
Keep it brief:
- Who you are (1-2 sentences)
- What you're interested in or working on
- How to reach you
- Links to portfolio or LinkedIn
- A direct route to the work most relevant to the role
Avoid:
- Walls of text
- Excessive badges and stats
- Claims without proof ("10x developer")
What repositories should you pin on GitHub?
GitHub currently displays up to six public repositories or gists in the pinned section. You can pin a repository you own or one you contributed to within the last year, subject to GitHub's eligibility rules. You do not need to fill every slot.
Pin:
- Your strongest role-relevant projects
- Open source contributions (if substantial)
- Useful tools you've built
Don't pin:
- Tutorial follow-alongs
- Forked repos you haven't modified
- Half-finished experiments
How important is the GitHub contribution graph?
The contribution graph is incomplete evidence. GitHub applies rules about repository type, branch, commit email, account relationship, access, and privacy; private activity can be anonymized, and viewers only see repositories they may access.
Do not optimize for a streak. Make selected projects, pull requests, issues, decisions, and outcomes understandable. A quiet graph may reflect private employment, another forge, study, caregiving, or a role where coding is not the only output; it is not a reliable measure of quality or consistency.
Common Mistakes Questions
These patterns can make a portfolio harder to evaluate. Fix the evidence gap rather than applying a universal rule.
How can tutorial-derived projects become useful portfolio evidence?
A tutorial clone is weak evidence when it hides what the author decided or implemented. The topic itself is not the problem; undisclosed copying and lack of role-relevant decisions are.
Bad: Todo app that matches the tutorial exactly
Better: Todo app with one justified extension, tests, and documented authorship
Also valid: A different small problem with real constraints and a verifiable outcome
What should you provide when a live demo is impractical?
A broken or unsafe demo is worse than an honest alternative. Choose among a live deployment, isolated sandbox, recording, screenshots, generated API documentation, package example, or reproducible local setup according to the project.
If you deploy, verify current price, inactivity, resource, region, data-retention, and acceptable-use terms. Add health monitoring or a visible status note, synthetic data, cost limits, and a teardown path. Static hosting can suit static artifacts; stateful systems need a deliberately secured runtime and data store.
Why do missing READMEs hurt your portfolio?
A missing README forces the reviewer to infer the project's purpose, status, ownership, and setup. GitHub surfaces a recognized README prominently, so even a concise document should explain what and why, how to evaluate it, prerequisites, verification, maintenance status, limitations, and attribution.
How should you present unfinished or experimental projects?
Experiments and unfinished work are normal. The problem is presenting them as finished or making the relevant work difficult to find.
Clean up your GitHub:
- Unpin irrelevant projects and label status clearly
- Archive an inactive repository when that accurately communicates its state
- Keep useful learning history when it supports your story
- Check incoming links before renaming, privatizing, archiving, or deleting anything
How do outdated dependencies hurt your portfolio?
An older dependency may be a deliberate compatibility constraint, not proof of neglect. The real problems are an unreproducible build, unsupported runtime without explanation, unresolved exploitable vulnerabilities, or a demo that no longer matches its documentation.
Maintenance checklist:
- Keep a lockfile and document the supported runtime
- Run tests, lint/type checks, and a production build in CI
- Triage dependency and code-scanning alerts rather than updating blindly
- Test upgrades and record accepted risk or compatibility constraints
- Test that the live demo still works
Portfolio Strategy Questions
Build the smallest set of evidence that covers the requirements of the roles you target.
How should you start building your portfolio?
Start from a target job description and create an evidence matrix: requirement, artifact that demonstrates it, and verification path. One completed project is a practical starting point, but a smaller contribution or case study may be better for a narrow gap.
A strong first project has:
- Clear problem it solves
- Clean, well-documented code
- Live demo
- Comprehensive README
- Meaningful commit history
How do you add variety to your portfolio?
Add another project only when it closes a meaningful evidence gap. Possible coverage includes:
For frontend roles:
- Accessible interaction and responsive layout
- Async data, state, and failure behavior
- Performance measurement or design-system reasoning
For backend roles:
- API contracts, validation, and persistence
- Authorization, data modeling, and migrations
- Reliability, observability, jobs, or integration failure
For full-stack roles:
- One end-to-end user flow and its trust boundaries
- A deeper frontend or backend decision relevant to the role
- Deployment, compatibility, telemetry, and recovery evidence
These are dimensions, not a prescribed number of repositories. The same project can cover several when the README points to concrete proof.
Should you contribute to open source for your portfolio?
Open-source contributions can show work in an existing codebase and public collaboration, but they are optional and access to unpaid contribution time is unequal.
Good first contributions:
- Documentation improvements requested by the project
- Bug fixes with reproduction and regression tests
- Scoped features aligned with maintainer guidance
Don't:
- Send unsolicited trivial PRs just to show activity
- Contribute to projects you don't understand
- Expect open source to replace portfolio projects
- Ignore contribution guidelines, maintainer time, licensing, or disclosure rules
Quick Reference
Portfolio essentials:
- Role-relevant evidence with clear authorship
- A safe, low-friction evaluation path
- Honest scope, status, constraints, and limitations
README must-haves:
- Problem, users or assumptions, and current status
- Demo, recording, screenshots, package example, or local setup
- Architecture, decisions, verification, and limitations
- Security/privacy notes, license, and attribution
GitHub profile:
- Optional concise profile README
- A curated set of relevant eligible pins
- No manufactured contribution streak
Common mistakes to avoid:
- Unclear ownership or copied work without attribution
- Broken, unsafe, or unexplained evaluation paths
- Missing setup, verification, or status documentation
- Claims unsupported by tests or evidence
- Untriaged vulnerabilities and unreproducible builds
Frequently Asked Questions
How many portfolio projects do I need as a junior developer?
There is no universal number. Start with one role-relevant project you can explain deeply, then add projects only when they demonstrate different evidence. A small, maintained set with documentation, tests, and clear ownership is usually more useful than a large list of shallow repositories.
What portfolio projects impress interviewers most?
The strongest project is relevant to the target role and makes your decisions verifiable through code, documentation, tests, and a usable evaluation path. A real user problem can help, but a carefully scoped simulation or extended course project can also be credible when its constraints and your contribution are explicit.
Should I build a todo app for my portfolio?
A todo app is acceptable if it demonstrates decisions relevant to the role rather than copying a tutorial unchanged. Add only features that create useful evidence, such as accessibility, offline behavior, authorization, conflict handling, testing, or observability, and document what you designed yourself.
Do I need a personal website as a developer?
No. A concise résumé plus accessible repositories, documentation, and demos can be enough. Build a personal site when it improves discovery or itself demonstrates relevant frontend skills; otherwise keep the evaluation path simple and invest effort in evidence aligned with the role.
How important is GitHub contribution history for getting hired?
Treat the contribution graph as context, not a hiring score. Visibility depends on repository access, privacy settings, branch and attribution rules, so it is incomplete evidence. Curate role-relevant repositories and explain decisions instead of manufacturing a streak or judging quality by green squares.
Can bootcamp projects count in my portfolio?
Yes. Attribute the starter material and team contributions, identify the baseline, and describe exactly what you designed, changed, tested, and learned. Extend the project only when the changes create relevant evidence; do not imply sole authorship of shared or instructor-provided work.
Official Sources
- GitHub: Using your profile to enhance your résumé
- GitHub: Managing your profile README
- GitHub: Contributions on your profile
- GitHub: Profile contributions reference
- GitHub: About repository README files
- GitHub: Quickstart for securing your repository
- W3C WAI: Introduction to Web Accessibility
- W3C WAI: Images tutorial
Related Articles
- Complete Technical Interview Career Guide - The full interview process from application to offer
- Complete Frontend Developer Interview Guide - Technical prep for frontend roles
- Complete Node.js Backend Developer Interview Guide - Technical prep for backend roles