W41–W44: Hardening & Documentation (README, diagrams, demos)

W41–W44: Hardening & Documentation (README, diagrams, demos)

What you’re doing

You turn your projects into portfolio assets that don’t look fake.

Most portfolios fail because:

• repo is messy
• no clear “how to run”
• no demo
• no screenshots
• no story

This phase is where you package your work like a professional engineer.

Time: 4–6 hours/week
Output: hardened repos + clear docs + diagrams + demo scripts so anyone can understand and run your projects

The promise (what you’ll have by the end)

By the end of W44 you will have:

• Each project repo has a strong README and “how to run”
• A short architecture diagram for each project
• A demo script / demo dataset for each project
• Consistent quality gates (tests, lint, basic CI if possible)
• A portfolio-ready “project page” summary you can link from your website

The rule: if a stranger can’t run it, it doesn’t count

Portfolio isn’t “I did something”.
Portfolio is:

• someone can verify it
• quickly
• without your help

What to harden (3 projects)

You should harden:

1. AI Ticket Analyzer
2. SAP Data Pipeline
3. Knowledge Base + RAG

Same packaging standards across all three.

Step-by-step checklist

1) Upgrade README (minimum structure)

Every README should include:

• what this is (1 paragraph)
• why it exists (pain point)
• architecture (short)
• how to run (copy/paste)
• how to test
• demo (example commands + expected outputs)
• limitations (honest)
• roadmap (next improvements)

Short and sharp beats long and fluffy.

2) Add diagrams (simple but clear)

You need:

• one system diagram per project
• optionally one data flow diagram

Use any tool:

• Mermaid
• draw.io
• even a simple PNG

But the diagram must explain the core flow.

3) Create a demo mode

Every project needs a demo that works without secret access.

Examples:

• sample anonymized dataset
• mock extraction input
• local KB docs

Your goal: “demo works on any laptop”.

4) Add a quality gate baseline

Minimum:

• tests run in one command
• lint/format stable
• CI runs tests (optional but great)

Remember W6: reproducible > fancy.

5) Create a project summary page on your site

On MetalHatsCats (or your site) add:

• what the project solves
• demo screenshots
• link to repo
• what you learned

This is how you turn code into credibility.

Deliverables (you must ship these)

Deliverable A — Portfolio-grade READMEs

• 3 READMEs updated
• clear run/test/demo instructions

Deliverable B — Architecture diagrams

• 3 diagrams (one per project)
• included in READMEs

Deliverable C — Demo kits

• demo datasets/scripts exist
• demo works locally

Deliverable D — Quality gates

• tests/lint runnable
• CI if possible

Common traps (don’t do this)

Docs are verification.

• Trap 1: “Docs are marketing.”

No. Demo must work with anonymized/mock inputs.

• Trap 2: “Demo depends on real SAP access.”

Later means never. Package now.

• Trap 3: “I’ll clean repos later.”

Quick self-check (2 minutes)

Answer yes/no:

• Can a stranger run each project in 10 minutes?
• Are READMEs clear and honest?
• Do diagrams explain the flow without a meeting?
• Is there a demo dataset / demo script for each project?
• Would I be proud to send this repo link to a hiring manager?

If any “no” — fix it before moving on.