Publish nothing you would not want opened on a projector

The Projector as a Judge

When a recruiter opens a link on their laptop, they often do it in a room where they will speak to the author of that link. The screen becomes the judge, the projector the magnifying glass that pulls every decision into view. You should treat every artifact you publish as a live interview in disguise. If an artifact is sloppy, the interview is ruined before you even speak a word.

You can’t rely on a recruiter to “gloss over” a messy README or a broken demo. In an era where digital portfolios are the first impression, the artifact you leave on the internet is the person you’re presenting to the world. It’s a conversation that will happen before any conversation ever happens. The way you handle this conversation can determine how you are perceived by recruiters, hiring managers, and even future coworkers.

The Half‑Finished Demo Problem

A half‑finished demo looks like a story that never ends. It says, “We have a working part, but the rest is still on the table.” That is a narrative recruiters can read. It suggests a lack of discipline in shipping, an inability to see a project through, or a fear of failing to deliver a full experience. When a recruiter sees a demo that stops halfway, they automatically wonder why it stopped. The narrative of unfinished work often outweighs any functional portion you manage to showcase.

A simple approach to avoid this trap is to ship a complete, minimal, working demo that can be executed out of the box. You don’t need to build a polished UI or integrate every feature. Just make sure the core workflow you intend to highlight is operational. Once the demo is ready, you can document it later. A polished demo demonstrates that you can deliver. A broken or incomplete demo tells the opposite story.

When to Ship Early

You might think that waiting until every feature is polished is the best path. That is a myth. The reality is that the “ready” state you choose should be driven by the interview narrative you want to craft. If you want to show that you are a fast, efficient shipper, release a demo that works even if it is minimal. If you want to demonstrate deep craftsmanship, you can build a richer demo. The key is that the artifact you publish must be a coherent, finished product, even if it is small.

Decisions in READMEs

A README is not just a file; it is a conversation starter. A tiny repository with a concise README that explains the design decisions often wins over a large repository with no documentation. Recruiters skim quickly. They want to know what you did and why you did it. A well‑crafted README turns a raw codebase into a narrative that can be followed without having to run the code.

What Makes a Good README

1. Purpose, State what the repository is for, what problem it solves, and why it matters.
2. Setup, Give a clear set of steps to get the project running locally. Include any environment variables or configuration needed.
3. Architecture Overview, A diagram or a short paragraph explaining how the components interact. Visuals help the recruiter understand your design at a glance.
4. Decision Log, Document key choices: why you chose a particular framework, why a data model looks the way it does, any trade‑offs you weighed. This shows that you considered alternatives and made informed decisions.
5. Future Work, Briefly note what could be added next. This signals that you have a vision beyond the current artifact.

A README that covers these points turns a tiny repo into a compelling interview. Even if the code itself is small, the explanation makes the project feel complete.

Avoiding a Large, Undocumented Repo

When you have a large repository with many files, the default impression is that the project is complex. That can be positive, but only if the recruiter can see the complexity in a manageable way. If the repo is just a collection of code with no documentation, it reads as a chaotic stack of files. Recruiters will suspect that the code is difficult to maintain or that you are not comfortable explaining your work. Therefore, if you choose a larger repo, pair it with a README that breaks it into digestible parts. If you do not have time to document, consider simplifying the repo instead.

Pulling the Embarrassing Artifact

You will inevitably have artifacts that, in hindsight, do not reflect the level of polish you aspire to. Maybe a prototype that crashed, a repository with a broken dependency, or a design that turned out to be a dead end. The temptation is to keep them as evidence of “learning.” However, those artifacts are interview bait that will likely be asked about in a negative light. The better option is to pull them.

Pulling a repo or demo means removing it from public view. That can be done by deleting the repository or making it private. The key is that the public portfolio should only contain artifacts that you are proud to present. When a recruiter asks about the missing artifact, you can respond that the project was an experimental phase and is no longer part of the active portfolio.

How to Justify Pulling an Artifact

If you must explain why a project was removed, frame it as a learning moment: “This project taught me X, and I now apply X in my current work.” You can still mention the lessons learned without exposing the messy code or design. This preserves the narrative of growth while keeping the portfolio clean.

Building a Culture of Interview‑Ready Portfolios

The practices above are individual steps, but they belong to a larger culture. Treat your portfolio as a living, breathing tool that you refine regularly. Consider the following habits:

1. Iterate on Readme, Whenever you add a new artifact, update its README to include the decision log and architecture diagram. Treat the README as part of the product, not an afterthought.
2. Maintain Minimal Viable Demos, Keep a list of small, functional demos that demonstrate core skills. Rotate them out of the portfolio as you add better ones.
3. Audit Public Repositories, Periodically review public repos for any that do not meet the interview‑ready standard. Pull or archive them.
4. Document Lessons Learned, When you finish a project, write a short reflection that can be attached to a new artifact. This builds a narrative of continuous improvement.
5. Seek Peer Review, Ask a colleague to review your portfolio. A fresh pair of eyes can spot unfinished artifacts you might have missed.

Adopting these habits ensures that every link you share tells a concise, honest story of your work. Recruiters will recognize that you ship complete artifacts, explain your decisions clearly, and are comfortable removing or hiding parts that no longer represent your capabilities.

The Role of Tooling

You don’t need a fancy tool to enforce these practices, but a simple workflow can help. For example, a script that checks for the presence of a README, verifies that a demo can be built from the command line, and flags any broken links in the documentation. Automation reduces the cognitive load of maintaining a clean portfolio and guarantees that the artifact you publish matches the story you want to tell.

When you publish, think of it as scheduling a meeting: the artifact is the room, the README is the agenda, and the demo is the presentation. If you come unprepared, the meeting will fail.

Final Thought

Every linked artifact you share is an interview waiting to happen. Treat it with the same care you would give a live presentation. Ship complete demos, write clear READMEs that explain why you built what you built, and remove any piece that might distract from the narrative you want to create. By building a portfolio that consistently looks like a polished interview, you make the recruiting process easier for everyone involved. If you need a tool that automates part of this workflow, consider exploring a self‑hosted solution that fits the mechanics of job hunting, such as Hunta.