I was looking back at some of my old GitHub repositories from a few years ago, and it hit me: most of them were essentially "code graveyards." I had these scripts that worked perfectly on my machine, but to anyone else, they were just walls of uncontextualized R code. If I were a hiring manager spending only three minutes on a portfolio, I'd have no idea what the goal was or why the results mattered. We need to fix that.

The "Script Dump" Trap

Let's say I have a project where I analyzed NYC Citi Bike trip data to find the most efficient docking stations. My first instinct—the lazy engineer instinct—is to just push my analysis.R script to GitHub. I'll try that now.

# analysis.R
library(tidyverse)
df <- read_csv("citi_bike_data.csv")
summary_stats <- df %>% group_by(station_id) %>% summarize(avg_trip = mean(tripduration))
ggplot(summary_stats, aes(x=station_id, y=avg_trip)) + geom_col()
# ... 200 more lines of data cleaning ...

I'm looking at this in the GitHub UI, and it's bleak. There's no explanation of the dataset, no "so what," and the plots are trapped in my local /plots folder. A recruiter isn't going to clone my repo, install the same version of tidyverse I used, and run the script just to see if I know how to use a dataframe. That's a huge friction point. I need to move from "sharing code" to "presenting a project."

Turning Code into a Narrative

The fix here isn't just a better README; it's changing the medium. I'm going to move this into a Quarto (or R Markdown) document. The goal is to weave the code into a story. I'll try rendering a section of my analysis to see if the flow feels more natural.

## The Efficiency Gap in Midtown
I noticed that several stations in Midtown have a massive imbalance in trip duration. 

```{r}
#| echo: false
# I'm hiding the tedious cleaning code here so the reader 
# focuses on the insight, not the regex.
ggplot(summary_stats, aes(x=station_id, y=avg_trip)) + 
  geom_col(fill = "steelblue") + 
  theme_minimal() +
  labs(title = "Average Trip Duration by Station")
```

As you can see above, Station 123 is an outlier. This suggests...

Now we're getting somewhere. By using echo: false for the boring parts and keeping the "meat" of the logic visible, I'm guiding the reader. I'm not just showing them I can write R; I'm showing them I can derive a business insight from data. That's the difference between a coder and a data professional.

The Last Mile: Making it Public

Even with a Quarto doc, if the recruiter has to download a .qmd file, we're back to the friction problem. I want this to be a one-click experience. I'll try rendering this to an HTML file and hosting it via GitHub Pages.

I noticed a common mistake I used to make: uploading the raw .csv file to the repo. If the dataset is 500MB, the repo becomes sluggish and might even hit GitHub's limits. Instead, I'll host the data on a public S3 bucket or a Dropbox link and use read_csv("https://...") in the code. This keeps the portfolio lean and ensures the project is reproducible regardless of the user's local file structure.

Once I push the index.html to my gh-pages branch, my project is no longer a "folder of scripts"—it's a live case study. I can put a link to this in my resume, and the hiring manager sees the result immediately. My R skills are now an evidence-based claim rather than just a bullet point.

📋 Practical Task

Transforming a Raw Script into a Public Case Study

You have a raw R script called weather_analysis.R that calculates the average temperature increase over ten years using a public dataset. Your goal is to turn this from a "script dump" into a portfolio piece.

• Step 1: Create a Quarto (.qmd) or R Markdown (.Rmd) file. Instead of just listing the code, write two paragraphs: one explaining the "Problem" (why this analysis matters) and one explaining the "Insight" (what the data actually tells us).
• Step 2: Organize your code chunks. Use echo: false for the data loading and cleaning sections, but keep the ggplot2 visualization code visible so the reviewer can see your styling logic.
• Step 3: Replace any local file paths (e.g., read.csv("C:/Users/Documents/data.csv")) with a URL to a public CSV file to ensure the project is reproducible.
• Step 4: Render the document to HTML and describe (or simulate) the process of pushing it to a GitHub repository and enabling GitHub Pages to make it a live URL.