How to Write Portfolio Project Descriptions

Start with the problem and your role

Name the intended user or audience and the problem you set out to address. Give enough context for someone outside your course, company or field. Then state your role: individual project, team contribution, client engagement or self-directed concept.

A title like “Reservation API for a shared workspace” is easier to interpret than “Project 03.” The opening sentence should describe the work itself rather than a list of adjectives about its quality.

Use a five-part outline

You do not need five headings on every project card. The outline is a writing aid. A short card might cover it in a paragraph and link to a longer account; a substantial case study can use separate sections.

• Context: who the project serves and why it exists.
• Scope: the deliverable and the constraints you worked within.
• Contribution: the parts you were responsible for.
• Decision: one important choice and why you made it.
• Evidence: the finished work, a working behavior, a result or a limitation.

Developer example: replace the stack list with behavior

“React, Node and PostgreSQL” tells a reader which tools were involved. Add what those tools made possible and what you implemented. Mention tests or performance only with enough detail to make the claim meaningful.

Illustrative description: “I built an appointment booking prototype for an invented tutoring service. I implemented the calendar interface and booking API, including validation for overlapping times. Tests cover invalid ranges and duplicate bookings. The demo uses sample data and has no payment integration.”

Designer example: identify the reasoning and the limits

A final mockup shows the design but may not show how you arrived at it. Explain a decision about navigation, hierarchy, layout or language. Separate observed feedback from assumptions, and label untested concepts.

Illustrative description: “For this personal concept, I redesigned a workshop signup flow around one primary action. I reduced competing navigation on the form and added a summary before confirmation. The prototype demonstrates the interaction; it has not been validated with workshop customers.”

Freelancer example: describe the scope of the deliverable

A potential client needs to understand the kind of work you can deliver. State the brief, what you supplied and where the scope ended. When you cannot share a client name or result, use a permitted description without making a vague performance claim.

Illustrative description: “This sample newsletter sequence introduces an independent bookshop’s monthly reading club. I wrote the welcome email, event reminder and follow-up using an invented brief. The sequence demonstrates tone and structure; it has not been sent to a customer list.”

Support the description with the right artifact

Choose a screenshot, demo, repository, document or video that directly relates to the description. Add a caption that tells a reader what to look for. A screenshot of a homepage does not support a claim about a complex backend feature unless you also explain or show the underlying behavior.

Check that public links work without your account. Remove credentials and private data from screenshots. If the only available evidence is confidential, summarize what you are allowed to disclose and state the limit.

Edit out claims you cannot defend

In PortfolioBuild, use the project section to present the short version and relevant links. Review the page in the chosen template so the most useful context is visible before a reader leaves to inspect the work.

• Replace “revolutionary” with the specific behavior or decision.
• Replace unsupported percentage improvements with an observable result.
• Replace “we built” with your contribution when role clarity matters.
• Credit starter code, templates and collaborators.
• State whether the work is live, a prototype, a concept or archived.
• Keep the title, project link and screenshot consistent with the written account.

Related guides

• How to Turn Your CV into a Portfolio Website
• How to Make a Portfolio with No Experience