A journalist-developer portfolio is a small website that proves both halves of a hybrid newsroom role: editorial judgment and shipped technical work. The formula is simple. Pick two to four finished projects, give each one a short case study explaining the reporting problem, the data, the decisions and the outcome, and link the live thing. Editors read the reasoning, engineers read the build, and the same page serves both.
That combination is what makes the portfolio different from a clips folder. Clips show that you can write. A well-documented case study shows how you chose a dataset, what you threw away, when you pushed back on an editor, and whether the piece helped anyone. On a team, the same site doubles as the handoff document a replacement developer would read.
Most people get stuck before they start, because the decision feels like picking a platform and the platform debate eats a month. It is the second decision. The first one is choosing the work. This guide walks through the whole build, including the part nobody mentions: how to document newsroom work you are not allowed to show.
Table of Contents
- What You Need to Build a Portfolio as a Journalist Developer
- Step-by-Step: Build a Journalist Developer Portfolio
- Common Mistakes
- Frequently Asked Questions
- Is GitHub a portfolio website?
- What are good GitHub projects to include on my resume?
- How do I build a journalism portfolio with no published work?
- How do I showcase a project that is behind a paywall or under embargo?
- How do I order the same portfolio for a job application and a freelance pitch?
- How long should a portfolio website take to build?
- Conclusion
What You Need to Build a Portfolio as a Journalist Developer
Gather these before you touch a template. A half-hour of sorting saves a weekend of moving text around later.
- Two to four projects. Finished beats nearly finished. If something is unpublished and unembargoed right now, it counts; if it is a concept, it does not.
- The source trail. Links to the datasets you used, the records you requested, the notebooks you cleaned the data in, and the APIs you called.
- Outcomes, even small ones. Pageviews, time on page, hours saved per week, how many editors used the tool, how fast the story shipped.
- Live links and a way to reach the work. The public piece, the live app, the repository. If a project is gone, you need a screenshot set and a short explanation of why.
- Clean screenshots and short clips. Static images for layouts, a ten-second screen recording for anything interactive. Readers should see the finished experience, not just a thumbnail.
- A hosting decision. A name and somewhere to put it. A static site on a free host is enough for most people, and a personal domain costs one small annual fee.
- A plan for the work you cannot show. Roughly a third of a career’s projects sit behind an embargo, a paywall, or a source agreement. Decide now what those pages will look like.
Two things are worth writing down before you start. First, one sentence describing what you do and who for. Second, the three kinds of reader you expect, because they will not read in the same order.
Step-by-Step: Build a Journalist Developer Portfolio
Six steps, in the order that avoids rework. Each one ends with a check, so you know it worked before moving on.
Choose projects that show editorial judgment
Pick two to four projects that show how you identified an audience need, worked inside real constraints, and produced something useful. A clever chart nobody needed is weaker evidence than a modest tracker that twelve editors opened every week.
Score each candidate on three things: was there a real editorial question, were there constraints you had to design around, and can you name what changed after it shipped. Drop anything where you cannot answer the third one, even if the visual work is your best.
Editors on r/editors put it more bluntly than the guides do: show the work you want more of. Curating toward a target beat or role is not spin, it is how the reader finds you in five seconds.
The check: a stranger can tell from your shortlist alone what kind of problems you solve.
Write the problem and your role clearly
Open every case study with the same five beats. The problem, who had it, the constraints you were handed, who you worked with, and the specific part that was yours.
That last one is where portfolios go wrong. Team projects produce a blur where every contributor sounds like the lead. Name your own decisions: the dataset you rejected, the story structure you proposed, the accessibility fix you pushed for in review.
Credit colleagues by name and role. It costs you nothing and it tells an editor you understand how newsrooms actually work, which is half the job.
The check: the page tells the reader what you decided, not only what your team produced.
Show the technical system without overloading the story
Editors want the story. Engineers want the plumbing. Put both on one page and let the reader choose their depth.
Document the data sources with links, the shape of the system in a few sentences or a small diagram, the tools, and the trade-offs you accepted. A short list of decisions beats a tech stack dump. Something like: a scheduled scrape refreshed hourly because the source had no API; a static build because the page rarely changes and readers are often on slow connections.
Publish the intermediate work where you can. A cleaned notebook, a public repository, a query you ran against a records portal. On r/ExperiencedDevs the consensus is that shipped work outweighs a portfolio once you have experience, and the write-up is what connects the shipped work back to you.
The check: an engineer can name your data sources without emailing you.
Document the result and its impact
Put numbers where you have them and honest sentences where you do not. Traffic, time saved, publication speed, how many colleagues adopted the tool, whether the methodology caught an error before publication, what readers did next.
Include the parts that did not work. A tracker that was never used, a chart that confused readers in testing, a first version you threw away. In a newsroom portfolio this reads as judgment rather than as failure, and it is the fastest way to look like someone who has actually shipped.
If the work is recent and the numbers are thin, say what you would measure and why. Editors understand that a story published last month has no meaningful traffic history yet.
The check: each project has at least one concrete sentence of evidence, and one sentence about what you would change.
Present the work on a simple, credible portfolio site
The site is a delivery mechanism, so keep it boring. A homepage with your one-line positioning, three to five featured projects, a short bio, and a contact method. Then one page per project using the frame above.
| Option | Time to launch | Control | Suits |
|---|---|---|---|
| Squarespace, Webflow, Wix | An afternoon | Layout only, no hosting control | Applying as a reporter or editor, or pitching clients fast |
| GitHub Pages with Jekyll, Eleventy, or Hugo | A weekend | Full markup and hosting, static only | Most journalist-developers starting out |
| A custom JavaScript build such as React or Next | Days | Everything | Applying for an engineering role, where the site is itself a demo |
That table is the whole platform debate. GitHub Pages is good for simple static pages and wrong for anything database-backed, which is why the third row exists at all. Hand-coding a portfolio while applying for a reporting role is a common detour, and the writers’ forums are full of people who lost weeks to it.
Buy the domain name you actually want, keep GitHub as the source of truth for anything code-based, and set the profile README to link to the site. Your GitHub profile is a portfolio page with a smaller audience, not a replacement for one.
The check: the site loads fast on a phone, every link works, and your positioning sentence is visible without scrolling.
Polish the portfolio for a hiring audience
Read every page out loud once and cut anything that slows the reader down. Fix the typos, then check the small stuff that quietly costs you interviews: alt text on images, headings in order, colour contrast, keyboard navigation, and a page that does not shift while loading.
Then order the site for the reader in front of you. The same portfolio gets three cuts. For a newsroom job application, lead with the projects closest to the role and put technical depth in the body. For a freelance pitch, lead with the outcome for the client and the turnaround time, and keep the build notes lower down. For a conference or fellowship panel, lead with public work, talks and awards, since outside judges cannot see your internal tools.
Publish it, then ask three people to use it without explaining anything. Watch where they hesitate. That hesitation is your next revision, and it is a better signal than any template checklist.
The check: a stranger can tell what you do, find the proof, and contact you in under two minutes.
Common Mistakes
- Publishing a finished graphic with no context. Fix: add three sentences on the reporting question, the data, and what changed because of the piece. The image is the least interesting part.
- Listing every technology you have ever opened. A long tool list reads as padding. Name the tools that belonged to each project and why, then stop.
- Hiding the editorial decisions. If a developer only sees the build, they assume a designer or an editor supplied the thinking. Put your reasoning in plain language.
- Linking to private repositories. A dead private link reads as a broken site. Mirror the public parts somewhere reachable and say clearly that the original is internal.
- Making the portfolio a dumping ground. Every piece you ever wrote buries the three you want more of. Two to four strong projects beat a full archive.
- Spending a month on the stack. Pick from the table, ship, and revise. A plain site published this week beats a beautiful one in six weeks, and half-finished portfolios are the most common outcome in the forum threads about this.
- Leaving confidential work out entirely. Plenty of strong projects can never be shown. A redacted case study, a written account of a system you cannot publish, or a personal project built in the same style all count. Silence reads as a gap in your record.
Frequently Asked Questions
Is GitHub a portfolio website?
Treat GitHub as supporting evidence, not the portfolio itself. Your profile, pinned repositories and README show engineering ability well, but they do not explain the reporting problem, the editorial decision, or the outcome, and most readers will never go looking for those. Build a simple site and point your GitHub profile at it. For developer roles the reverse sometimes works, though the case studies are still what separate one application from another.
What are good GitHub projects to include on my resume?
Include work where the code exists because the journalism required it: a scraper for a public records portal, a data cleaning notebook, a small tool your newsroom actually adopted, or a fix contributed to an open-source project. Each one should have a README that states the problem, the data, how to run it, and what came out of it. A polished tutorial repository counts too, since writing the explanation is half the job.
How do I build a journalism portfolio with no published work?
Build two or three self-directed projects end to end: request public records and publish what you find, replicate a published data story from scratch and document the differences, or build a small tool that solves a real newsroom annoyance. Student and fellowship projects count, as do class assignments with a real dataset. Label them honestly, describe the editorial question each one answered, and the gap stops being the story.
How do I showcase a project that is behind a paywall or under embargo?
Describe the work without exposing it. Explain the audience, the editorial problem, the constraints, your decisions and the outcome, then use a heavily redacted screenshot or a written walkthrough. Say plainly that the piece is behind a paywall and link to the public version if one exists. Never let a draft, a data file or a source detail slip into a case study to fill the gap, and check any agreement you signed before you publish a description.
How do I order the same portfolio for a job application and a freelance pitch?
Keep one set of case studies and change the front page. For a job application, lead with the projects closest to the role and let technical depth sit in the body. For a freelance pitch, lead with the result for the client, the turnaround, and one sentence on your process. For a conference or fellowship, lead with public work, talks and awards. Only the order and the emphasis change, so maintaining it is an hour, not a rebuild.
How long should a portfolio website take to build?
A template site with three written case studies is a realistic weekend. A GitHub Pages build with a custom domain and four projects is closer to two weeks once you factor in writing. A custom JavaScript build takes longer, but for a developer role the site counts as a demo, so the hours earn their place. Most stalled portfolios are not slow to build, they are slow to write, which is why the case-study template matters more than the tooling.
Conclusion
Learning how to build a portfolio as a journalist developer comes down to one habit: write down what you decided, not just what you built. Choose your strongest project, spend ninety minutes on a single case study using the five-beat frame, and put it online this week. The rest is editing, and editing is the easy part.
