I get asked about computer programmer portfolios. And the job hunt generally, but often that means talking about portfolios. I’m happy to give advice to whoever will listen.

Should you have a portfolio? How do I put together a portfolio? What would go into it?

Short Version First

In case you’re reading in a hurry: I think programmers should have a portfolio, including back-end programmers. A resume is okay but it’s not that useful for very senior folks. More important than either one is having a story.

But the interesting part is always the details. So: want to read some details?

Also, I have a portfolio that I wrote in simple static Javascript which you’re welcome to steal. The code looks big, but nearly all of it is the project data. The actual code is very small.

Why Portfolios?

It used to be pretty controversial to say a programmer needs a portfolio. These days people mostly accept it and schools tell younger developers they need them. Yay, progress!

That doesn’t just mean front-end programmers, though. I’m mostly a back-end programmer and I have a lot of that kind of project in my portfolio.

How would that help?

When I switched from back-end C programming to Ruby, it was a bit rough. My sales pitch went, “I’m expensive, I have ten years of experience, I have no commercial experience in your tech stack, hire me!” It took awhile to make the switch, as you’d guess.

But both recruiters and engineers were willing to give me a chance — and an interview — based on my portfolio. It took the place of commercial work that way. It also tends to work better because with work you can point out they can ask better questions.

I’ve met a number of early career engineers with similar stories. It’s the same general idea. The portfolio is an excellent way to show you can do a thing. It’s not as good as “I had this job doing this thing for years at a reputable company.” But it’s surprisingly close to that. And of course, having both is even better.

Making Things Visible

Even a back-end project is going to have some kind of visible interface, somewhere, even if only for debugging. Even a non-software project generally has some kind of visible interface. Even an all-audio project can be shown with waveforms or something.

At worst you can make an entry all-text, and that’s much better than nothing. But usually you can do better. For instance, here are some portfolio entries from mine…

YJIT is pretty invisible. But we needed a web site to show off its speed, so I have screenshots of that:

How Important Are Screenshots?

You might say, “how important are screenshots for programming projects anyway?” It’s a reasonable question.

Very important.

Even software engineers are human. We like visual stuff. We have a much easier time seeing than visualising. Screenshots are often pretty, and basically always easier to understand and more impressive than reading descriptions and figuring out what something “should” look like.

But is it important for back-end projects? Yes. Nothing I just wrote is in any way less applicable to back-end projects or back-end programmers. You could say “but a lot of back-end programmers have no portfolios!” This is true. Also a not-small number of them have resumes with bad spelling, bad grammar and are generally nearly unreadable. They are also frequently locked into their job because they couldn’t really leave if they wanted to. You could emulate this, but I’m going to suggest that you shouldn’t.

It’s really good to take screenshots.

A piece of writing or documentation? Screenshot it. Software with a control interface you didn’t write and you just changed the back end? Screenshot it. Plugin to a command line utility? Screenshot the console. Absolutely zero visual anything? Screenshot a chunk of the source code.

You could say, “hey, man, I’ve found stuff in your portfolio that doesn’t have screenshots”. And that’s true. In my defense, the vast majority of my stuff has screenshots. If you scroll through, you see lots of stuff with screenshots. One thing it is absolutely not is a wall of walls-of-text.

Also, keep watch for the occasional awesome personal project that makes for especially good screenshots. I won’t say you should work on them just for that reason, but if one comes your way, use it.

What Information Do You Need?

There’s no hard and fast rule for exactly what needs to be in a portfolio entry. But it’s good to keep in mind why you care.

This is a portfolio. You’re trying to convince readers of a few things. For instance, you might be trying to say:

• “I may be a junior programmer but I can put together a few interesting projects”
• “I’m an old programmer but I’ve learned new tech in the last few years”
• “I have a broad, diverse set of experiences — I’ve probably seen your problems before”
• “I have solid experience in React and Rails”
• “I’ve worked with LLMs so you can squeeze me like a sponge and money will drip out”

Your list will be unique to you. Think of it as your story. When figuring out what to say for each project, keep your story in mind. Want to emphasise LLMs? Have a “tools” section for projects and include which LLM-related tools you used. Talking up your deep experience? Mix recent projects using new tech with older projects on reliable tech.

I used to have a more complicated portfolio design with more mandatory sections. But especially as you add more projects, it can be hard to fit new projects into the old structure. My advice is keep it simple. Project name, date(s), chunk of descriptive text, screenshots. The descriptive text can include whatever you need it to &mdash languages, tools and libraries, what you worked on, etc.

For business projects, public open source projects and group projects be sure to say what you did for the project, not just what the project does in general. Similarly, it’s okay to have one or two “background” screenshots for the project, but the best ones are about what you personally built.

What About Secret Stuff?

Genuinely secret software is an interesting question. If you have official clearance from the US Department of Defense and work for a defence contractor, don’t take my word for anything about secrecy. But if you do, your company actually has a confidential legal team specifically so that you can share information on resumes, portfolios, etc. Get their opinion, not mine.

But that’s not why you asked. Actual secret stuff is handled by people who get very explicit warnings about what’s okay and what’s not. Instead, if you’re asking this, you work for a corporation who claim that breathing a word about their corporate strategy, metrics, numbers, employee names or anything is absolutely forbidden. That’s nearly every corporation, and in a legal sense they’re wrong. In some places they can still fire you, of course. California is an at-will state, and they can fire you for a lot less than that, and in many cases for no reason at all.

But realistically, engineers talk to each other about what they build. If you do a web search for the internal tool in question there may already be public screenshots out there, which are public info and you can use them. If it’s really an internal tool, screenshot something that won’t tell your competition much. Most internal tools have a basic and straightforward function that nearly all companies need. Here, I’ll pick an example where I’ve never worked there: Spotify has an internal dashboard in their Operations department showing uptime and CPU usage of internal services, complete with cryptic service names. I have never seen this dashboard. But I have great faith that it exists. If you put a screenshot of it in a portfolio, no actual corporate secrets of any kind will be revealed. Somebody knowing that it exists gives Spotify’s competition no information that they didn’t have already.

Most internal tooling is like that. It’s best if you can use public screenshots. But a tiny screenshot revealing no strategic information is easy to get and does nobody any actual harm. If necessary, screenshot less than the full window.

Should you run this by your company’s legal department? If you work in a DoD contractor with actual security clearance and they have a confidential legal group to do that, definitely. If you don’t, definitely not. The legal department in a random corporation works for them, not you. They are under no obligation to tell you the truth about any of this, nor to keep your query confidential. The company is going to claim that revealing “secret” information like “we have a dashboard and I made a customisable colour palette for it” is strategic and you’ve committed High Treason by revealing it to your competition. But they don’t care much unless you give them a reason to care.

Definitely don’t reveal any actual strategic information… which you almost certainly don’t know and couldn’t reveal if you wanted to.

But I’m Not a Front-End Programmer!

You may be saying, “hey man, you said you built that site full of graphs and metrics. Clearly you can do front-end.”

True. Guilty as charged.

If you’re a visual designer and you saw my portfolio you’re probably yelling at the screen “no he can’t!” Also guilty as charged.

But!

My portfolio has a nice simple structure with a minimum of design, using older standards (*cough* old Bootstrap *cough*) and you are extremely welcome to steal it.

If you view source it looks like a lot of lines of code. But mostly it’s a lot of portfolio entries as little divs, and a few hundred lines of actual code at the top. You will need to download the JS libraries it uses like an old copy of LightBox, but obviously you have the URLs to grab them with curl or wget.

In theory you could upgrade it to modern versions of everything pretty easily, though Lightbox is now under a more restrictive license. I’ve never seen the need. It’s easy to fiddle with architecture so much you never get an actual portfolio with actual screenshots actually online. Please do that first, whether you use my code or not. It could benefit from more of a build step, definitely… But if I were you, I’d go the other way. If any of the dynamic bits annoy you, change them to be simpler and static, even if there’s repetition. Get a simple static HTML page happening first. You can optimise once there’s something to optimise.