How to Explain a Portfolio Revision Without Hiding the Original Mistake
Show the revised project as your current work, and put a concise revision note beside it that names the original mistake and explains how you checked the change. A polished screenshot can show the result quickly; a short decision log lets a reviewer understand the reasoning and distinguish what you tested from what remains unknown.
You do not need to preserve a broken demo as the main experience or turn a small error into a dramatic story. Label the project as practice, identify your contribution, and make the earlier issue easy to find without making it the first obstacle to using the project. UC Berkeley’s Career Engagement guidance recognizes projects and portfolios as ways to communicate skills; the useful next step is to make your own contribution and evidence clear.
What should a reviewer see first?
Lead with the current version and one sentence describing its purpose. For example: “Practice project: a registration form demonstrating client-side validation. Revised after I found that an empty email could appear to submit successfully.” That sentence identifies the work, its scope, and the reason for the revision without implying it was a commercial product.
Place a current screenshot near that description, followed by a clearly labelled “Revision note” or “What changed” section. If you have a runnable demo or source repository, make those available from the project page. Identify which version the screenshot depicts and, if practical, identify the earlier revision by a commit or version label.
For a remote application, the project description should also make sense without a live explanation. You can use Talyca application planning resources alongside your application preparation to consider how the portfolio fits into the wider resume, cover letter, and interview process. Keep the project evidence on the project itself so that its explanation travels with it.
What does an honest revision look like in practice?
Consider a fictional registration form built as an individual practice project. Its first version has an email field and a submit button. When the field is empty and the user submits, the page shows “Registration complete.” That message is misleading: the demo has not collected a usable email address, and it does not actually create an account.
The original issue can be reproduced in three steps: open the original version, leave the email field empty, and select Submit. The expected behavior is an instruction to enter an email address, with no success message. The observed behavior is the success message. Naming both outcomes gives the reader a concrete failure to follow, rather than a vague statement that validation was improved.
In the hypothetical revision, the author adds a check for an empty value. If the field is empty, the form displays “Email is required” and does not show the success message. If the field contains a value that passes the demo’s stated check, the form can show a message indicating that the demo input was accepted. The author also changes the message so it does not suggest that a real account was created.
A focused check would submit an empty field and verify that the error is visible and the success message is absent. A second check would enter an example value, submit it, and verify the demo’s acceptance message. Playwright’s documentation describes assertions for checking visible text and other page conditions; an automated test can encode these expectations, while a manual check can document the same sequence.
The limitation matters: checking that a field is nonempty does not establish that an address is valid, deliverable, or owned by the person entering it. The example also has no server-side validation or real registration service. If only a manual check was performed, say so; if an automated test was run, identify the test and the environment actually used. Neither a screenshot nor an unrun test proves a passing result.
Should you use a screenshot, a decision log, or both?
Use both when the visual result and the reasoning each add something. A screenshot gives a quick view of the revised interface; a decision log explains behavior that a still image cannot establish. Keep each small enough that the project itself remains easy to inspect.
If space is tight, choose according to the claim you need to support. A screenshot is useful for showing the placement and wording of an error. A short log is more useful for explaining the failure, the chosen change, and the boundaries of a test. A screenshot of an error alone cannot show that the success state was suppressed or that the same behavior occurs in another browser.
Label an old screenshot “original version” and a new one “revised version.” If the original state is unavailable, describe the reproduction honestly instead of recreating an image and presenting it as historical evidence. Similarly, a commit or test file is useful supporting material only if it corresponds to the behavior described.
Format | Useful for | What it cannot establish alone
Current screenshot | Showing the revised form and error wording | Whether the interaction and checks work
Short decision log | Explaining the problem, choice, test, and limitation | That a described test was actually run or passed
Runnable demo or test | Allowing the reviewer to inspect behavior or checks | Coverage beyond the stated scenarios and environment
What should the revision note say?
Keep the note specific enough to reproduce. The following template works as a compact paragraph or as labelled lines on a project page: “Practice project and my role: [what I built]. Original issue: [what happened and under what conditions]. Reproduce: [starting state and steps]. Expected behavior: [what should have happened]. Change: [what I changed and why]. Check: [steps or test, environment, and observed result]. Limitation: [what remains untested or outside the project’s scope].”
For the fictional form, a finished note might read: “I built this registration form as a practice project. In the original version, submitting an empty email field displayed a registration success message. I reproduced it by leaving the field blank and selecting Submit. I added an empty-field check and changed the success wording to describe demo input rather than account creation. In a manual check of the revised version, an empty submission showed ‘Email is required’ and no success message; an example value showed the demo acceptance message. This check did not verify email deliverability or server-side behavior.”
Use that example as a model, not a result to copy. Replace every claim with the steps and observations from your own work. If a test failed, report the failure and the next action; if you have not run it, describe it as a planned check. If another person contributed, distinguish their work from yours.
How can a reviewer follow the evidence?
Give the project a short path: first read the purpose and practice-project label; next view the current screenshot or demo; then read the revision note; finally inspect the relevant code or test if more detail is useful. Use descriptive labels such as “Current demo,” “Revision note,” and “Validation test” wherever those materials are available.
Before sharing, follow that path yourself from the beginning. Check that the screenshot matches the current version, the reproduction steps identify the original version, and the note’s observed results match the checks you actually performed. Remove real personal information from example form entries and screenshots.
End the note with the next meaningful boundary, not a broad promise of quality. For the fictional form, that might be: “Next I would test additional input cases and add a server-side check if the demo were extended to store submissions.” This tells the reader what the current evidence covers and what further work would be needed.