Portfolio & GitHub polish — READMEs, diagrams, demos

Your GitHub is the proof behind the résumé — and the reader decides in 30 seconds

Section 1 of 5 · ~2 min

Yesterday’s résumé (Day 86) gets you the click; your GitHub is what closes it. A hiring manager who likes a bullet does exactly one thing next — opens the repo link — and forms a verdict in about 30 seconds, before reading a line of code. They are scanning, not studying. So the whole job of your profile and your top repos is to answer three questions fast: what is this, why does it exist, and can I see it run?

What converts, roughly in order:

1. A README that leads with what + why + a diagram — not installation steps. The first screen should say “linkstash is a URL shortener I containerized (Project 1), deployed on AWS (Project 2), then ran on Kubernetes/k3s (Project 3),” with an architecture diagram right there — reuse the ones you already drew across the three projects.
2. Pinned repos. GitHub lets you pin six; pin the three linkstash projects so they sit at the top of your profile instead of being buried under forks and tutorials.
3. A description and topics on each repo, so the profile card and search actually say something.
4. A clean commit history — real, incremental messages, not one squashed “final commit”.
5. A runnable demo — an asciinema cast or a short GIF — so the reader watches it work without cloning anything.

Real world: A README is a shop window, not a stockroom. Someone walking past decides in a glance whether to come in — a window crammed with wiring diagrams and supplier invoices sends them on; a window with the one product, lit, priced, and a “watch it work” screen pulls them through the door. Put the demo and the diagram in the window; leave the install minutiae in the stockroom further down.

A named example makes the order concrete. In 2010 Tom Preston-Werner, a GitHub co-founder, coined Readme-Driven Development: write the README before the code, because forcing yourself to describe what you’re building and why — in plain language, up top — is what makes the project legible to anyone who lands on it later. Whether or not you write it first, that order (what, then why, then how) is exactly what a 30-second scan needs, and it is the opposite of the framework’s default scaffold.

The three linkstash repos are your spine. Polished — each with a lead paragraph, a diagram, a quickstart, and a demo — they turn “candidate claims Docker, AWS, Kubernetes” into “candidate shows it, wired together, in three clicks.” Today you make the click pay off.

Hands-On Lab

Section 2 of 5 · ~3 min

Budget about 25 minutes. Nothing new to install beyond asciinema — you’re polishing the linkstash capstone repo you already built across Projects 1–3. Substitute your GitHub username for <you> throughout. The goal is a repo a stranger understands in 30 seconds.

First, rewrite the top of the README so the what and why come before any install step, with the architecture diagram right under them:

# linkstash

> Self-hosted URL shortener — POST a URL, get a short code that 307-redirects, from any device.

Containerized with Docker (Project 1), deployed on AWS (Project 2), and run on
Kubernetes / k3s (Project 3). This repo is the capstone that ties all three together.

## Architecture

![linkstash architecture](docs/architecture.svg)

## Quickstart

~~~bash
git clone https://github.com/<you>/linkstash && cd linkstash
docker compose up -d        # app on http://localhost:8080
~~~

## Teardown

~~~bash
docker compose down -v      # stops the stack and removes the data volume
~~~

## Demo

[![asciicast](https://asciinema.org/a/<id>.svg)](https://asciinema.org/a/<id>)

# 1. Before you push anything public, list tracked files that must never ship.
git ls-files | grep -E '\.tfstate|\.tfstate\.backup|kubeconfig|\.env$|\.pem$|id_rsa'
# Output — you want this EMPTY. Any line here is a secret already tracked by git:
# (no output = clean)

# .gitignore — keep state and secrets out of the repo for good
*.tfstate
*.tfstate.backup
.terraform/
kubeconfig
*.kubeconfig
.env
*.pem
id_rsa*

# 2. Commit the .gitignore with a real, specific message (not "update").
git add .gitignore
git commit -m "chore: ignore tfstate, kubeconfig and env files"
# Output:
# [main a1b2c3d] chore: ignore tfstate, kubeconfig and env files
#  1 file changed, 9 insertions(+)

# 3. Give the repo a description and topics so the profile card and search say something.
gh repo edit <you>/linkstash \
  --description "Self-hosted URL shortener: Docker to AWS to Kubernetes capstone" \
  --add-topic docker --add-topic aws --add-topic kubernetes --add-topic devops
# Output:
# ✓ Edited repository <you>/linkstash

# 4. Read it back the way a recruiter's profile card sees it.
gh repo view <you>/linkstash
# Output (trimmed):
# <you>/linkstash
# Self-hosted URL shortener: Docker to AWS to Kubernetes capstone
#   docker, aws, kubernetes, devops
# ...

Now pin the three projects. GitHub pins are set from your profile page, not the CLI: open github.com/<you>, click Customize your pins, and tick linkstash (Docker), the AWS deploy repo, and the k3s repo. Six slots exist — spend three on the projects that prove the résumé and leave the tutorial forks unpinned.

# 5. Record a runnable demo. Install asciinema, then start recording.
sudo apt-get install -y asciinema        # or: pipx install asciinema
asciinema rec linkstash-demo.cast
# Output:
# asciinema: recording asciicast to linkstash-demo.cast
# asciinema: press <ctrl-d> or type "exit" when you're done

# 6. Inside the recording, run the real quickstart so the cast shows it working, then exit.
docker compose up -d
curl -s localhost:8080/healthz           # {"status":"ok"}
exit
# Output:
# asciinema: recording finished
# asciinema: asciicast saved to linkstash-demo.cast

# 7. Upload the cast; asciinema returns a shareable URL for the README badge.
asciinema upload linkstash-demo.cast
# Output:
# View the recording at:
#     https://asciinema.org/a/123456

# 8. Paste that URL into the README Demo badge, then commit and push the polish.
git add README.md docs/architecture.svg
git commit -m "docs: lead README with what/why, architecture diagram and demo"
git push origin main
# Output:
#  2 files changed, 34 insertions(+), 61 deletions(-)
# To github.com:<you>/linkstash.git
#    a1b2c3d..e4f5a6b  main -> main

Open your profile in an incognito window and give it 30 seconds. Three pinned projects, each with a one-line what, a diagram, and a demo — that is the whole conversion, done.

Common Errors & Fixes

Section 3 of 5 · ~2 min

These are the portfolio mistakes that quietly cost interviews. None throws an error at you — that’s exactly why they survive until a reviewer clicks away.

Common error: Shipping the framework’s default scaffold README instead of describing your own project:

# Getting Started with Create React App
This project was bootstrapped with [Create React App].
## Available Scripts
In the project directory, you can run: `npm start` ...

Why: It describes the framework, not your project. A reader learns nothing about what linkstash does or why you built it — the 30-second scan comes up empty and they leave. Worse, it’s byte-identical to thousands of other repos, so it reads as “abandoned tutorial,” not “shipped project.”

Fix: Replace the top of the README with a one-line what + why and an architecture diagram, following the Readme-Driven-Development order. Push framework/dev boilerplate far below the fold, or into a CONTRIBUTING.md.

How you’d spot it: The first line of your README is the framework’s name, not your project’s. If Ctrl-F for your project’s purpose finds nothing above the fold, it’s scaffold — rewrite it.

Common error: Committing state or secrets — terraform.tfstate, a kubeconfig, or a .env — into a public repo:

$ git log --stat --oneline
e4f5a6b docs: update
3c2b1a0 add terraform
  infra/terraform.tfstate | 214 +++++++++++++++
  infra/.env              |   3 +++

Why: terraform.tfstate holds resource IDs and sometimes plaintext secrets; a committed .env or kubeconfig hands over live credentials. Deleting the file in a later commit does not help — it stays in history forever, and public repos are scraped by bots within minutes of the push.

Fix: Add a .gitignore first. If a secret was already pushed, rotate it immediately — assume it’s compromised — then purge history with git filter-repo (or the BFG) and force-push. Rotation matters more than the purge.

How you’d spot it: git ls-files | grep -E '\.tfstate|\.env|kubeconfig' returns a line, or GitHub’s secret-scanning emails you an alert. Treat any hit as a live incident, not a cleanup you’ll get to later.

Common error: Leaving 40 unpinned repos on the profile so the three that matter are buried:

Pinned:  (none)
Repositories (43):  react-tutorial · dotfiles · fork-of-vue · leetcode ·
   hello-world · test123 · linkstash · aws-linkstash · k3s-linkstash · ...

Why: GitHub sorts a profile by last pushed, so a tutorial fork you touched yesterday outranks the capstone you finished last month. The reader sees noise and never scrolls to the three repos that back your résumé.

Fix: Pin the three linkstash projects from Customize your pins; archive or delete dead experiments; give each pin a description so its card reads well.

How you’d spot it: Open your own profile in an incognito window for 30 seconds. If the three projects aren’t the first thing a stranger sees, the profile is working against you.

Portfolio & GitHub Interview Questions

Section 4 of 5 · ~1 min

Cover the answers below and say your own version out loud first — describe your GitHub profile and what a good README leads with before you reveal each answer. The four questions and answers render right after this note.

Go Deeper

Section 5 of 5 · ~1 min

Optional extras if you have ~25 more minutes:

• 5 min — Open your GitHub profile in an incognito window and time yourself: can a stranger tell what you build in 30 seconds? Note the first thing that isn’t a linkstash project.
• 10 min — Skim makeareadme.com and the standard-readme spec, then diff your linkstash README’s section order against their recommended order.
• 10 min — Record a second, tighter cast — under 60 seconds, no dead time — because a demo nobody watches to the end is a demo that didn’t land. asciinema rec --idle-time-limit 2 caps pauses at two seconds.