GitHub Portfolio: README, docs, demo, tests, architecture diagram
recruiter-ready repository (Series 10, Episode 02)
📑 এই পর্বে যা যা আছে
- ১. গল্প: recruiter link-এ ক্লিক করল
- ২. সমস্যা: ভালো কাজ, খারাপ repo
- ৩. কেন GitHub-ই junior-এর আসল CV
- ৪. একটা professional repo-র কাঠামো
- ৫. README: repo-র হৃদয়
- ৬. Reproducibility: "clone করে চালানো যায়" প্রমাণ
- ৭. Demo: দেখানো > বলা
- ৮. Tests ও architecture diagram
- ৯. GitHub profile ও pinned repo
- ১০. Job Requirement Decoder: "clean, documented code"
- ১১. সাধারণ ভুল
- ১২. Interview Prep
- ১৩. হাতে-কলমে
- ১৪. Project Connection
- ১৫. সারসংক্ষেপ
- ১৬. পরবর্তী পর্বে কী শিখব
🧩 ১. গল্প: recruiter link-এ ক্লিক করল
গত পর্বে Rahim CV ঠিক করল, GitHub link দিল। এবার একটা কোম্পানি সত্যিই সেই link-এ ক্লিক করল। কিন্তু
তারা যা দেখল সেটা হতাশাজনক — একটা repo যার নাম project-final-v2-real, ভেতরে শুধু একটা
Untitled.ipynb, কোনো README নেই, কোনো ব্যাখ্যা নেই। তারা বুঝতেই পারল না কাজটা কী।
Arif (ML Engineer বড় ভাই) Rahim-কে বলল:
"তোমার notebook-এ কাজটা হয়তো দারুণ। কিন্তু আমি ৩০ সেকেন্ডে সেটা বুঝতে না পারলে চলে যাব। GitHub repo হলো তোমার দোকানের সাজানো shelf — জিনিস ভালো হলেও যদি এলোমেলো পড়ে থাকে, কেউ কিনবে না। junior হিসেবে তোমার GitHub-ই তোমার সবচেয়ে জোরালো প্রমাণ — এটাকে অবহেলা করা মানে নিজের পায়ে কুড়াল মারা।"
"তোমার notebook-এ কাজটা হয়তো দারুণ। কিন্তু আমি ৩০ সেকেন্ডে সেটা বুঝতে না পারলে চলে যাব। GitHub repo হলো তোমার দোকানের সাজানো shelf — জিনিস ভালো হলেও যদি এলোমেলো পড়ে থাকে, কেউ কিনবে না। junior হিসেবে তোমার GitHub-ই তোমার সবচেয়ে জোরালো প্রমাণ — এটাকে অবহেলা করা মানে নিজের পায়ে কুড়াল মারা।"
এই পর্বে শিখব — কীভাবে একটা repo এমনভাবে সাজানো যায় যে recruiter/engineer ৩০ সেকেন্ডে বুঝে ফেলে: এই মানুষটা শুধু model বানায় না, একজন engineer-এর মতো কাজ করে।
😓 ২. সমস্যা: ভালো কাজ, খারাপ repo
বেশিরভাগ junior-এর GitHub-এ এই সমস্যাগুলো থাকে:
- শুধু একটা বিশাল
.ipynb, কোনো ব্যাখ্যা নেই - README নেই, বা শুধু default "# project" লেখা
- কীভাবে চালাতে হয় (setup, run) কোথাও লেখা নেই
- এলোমেলো commit: "asdf", "update", "final final"
- বিশাল dataset বা model file repo-তে push করা (repo ভারী, ক্লোন করা কষ্ট)
- API key/secret ভুল করে commit করা (বড় security signal)
মূল ধারণা: recruiter কোড লাইন-বাই-লাইন পড়ে না। তারা signal খোঁজে — README আছে?
চালানো যায়? পরিষ্কার structure? এই signal গুলোই বলে "এই মানুষটা team-এ কাজ করার জন্য প্রস্তুত"।
🤔 ৩. কেন GitHub-ই junior-এর আসল CV
Level 1 — সহজ intuition: CV বলে "আমি পারি"; GitHub দেখায় "আমি করেছি"। কথার
চেয়ে প্রমাণ সবসময় শক্তিশালী।
Level 2 — technical: একটা repo দিয়ে একসাথে অনেক skill প্রমাণ হয় — কোড লেখার মান, Git workflow, documentation, testing, deployment। এগুলো একটা লাইনে "I know Docker" বলার চেয়ে অনেক গভীর signal।
Level 3 — engineer perspective: senior engineer তোমার repo দেখে ভাবে "এই কোড আমার team-এ merge হলে কি আমার রাতের ঘুম নষ্ট হবে?" পরিষ্কার, reproducible, tested repo মানে "না, নষ্ট হবে না" — এটাই তোমাকে hire করার সিদ্ধান্তে সাহায্য করে।
Level 2 — technical: একটা repo দিয়ে একসাথে অনেক skill প্রমাণ হয় — কোড লেখার মান, Git workflow, documentation, testing, deployment। এগুলো একটা লাইনে "I know Docker" বলার চেয়ে অনেক গভীর signal।
Level 3 — engineer perspective: senior engineer তোমার repo দেখে ভাবে "এই কোড আমার team-এ merge হলে কি আমার রাতের ঘুম নষ্ট হবে?" পরিষ্কার, reproducible, tested repo মানে "না, নষ্ট হবে না" — এটাই তোমাকে hire করার সিদ্ধান্তে সাহায্য করে।
🏗️ ৪. একটা professional repo-র কাঠামো
একটা ML project repo মোটামুটি এভাবে সাজানো ভালো (একটা reasonable, পরিচিত pattern):
bd-tech-career-assistant/
├── README.md # প্রথমেই যা পড়া হয় - সবচেয়ে গুরুত্বপূর্ণ
├── requirements.txt # অথবা pyproject.toml
├── .gitignore # data/, .venv/, .env, __pycache__ ইত্যাদি
├── .env.example # secret-এর template (আসল .env নয়!)
├── data/ # gitignore করা (README-তে download link)
│ └── README.md # data কোথা থেকে, কীভাবে আনতে হবে
├── src/
│ └── career_assistant/
│ ├── __init__.py
│ ├── preprocess.py
│ ├── train.py
│ ├── predict.py
│ └── api.py # FastAPI app
├── notebooks/
│ └── 01_eda.ipynb # exploration - কিন্তু production code নয়
├── tests/
│ └── test_preprocess.py
├── models/ # gitignore (বড় file) বা release-এ রাখা
├── docs/
│ └── architecture.png
└── Dockerfile
বড় নীতি: exploration থাকবে
notebooks/-এ, কিন্তু আসল, reusable code
থাকবে src/-এ পরিষ্কার function/class হিসেবে। notebook থেকে .py-তে কোড সরানোই
junior থেকে engineer হওয়ার একটা বড় signal (Series 09-এর মূল শিক্ষা)।
📖 ৫. README: repo-র হৃদয়
README হলো একমাত্র জিনিস যা প্রায় সবাই পড়ে। একটা ভালো README এই প্রশ্নগুলোর উত্তর দেয়: এটা কী? কেন? কীভাবে চালাব? কী ফল?
# Bangladesh Tech Career Assistant
Job description থেকে skill বের করে এবং career প্রশ্নের উত্তর দেয় —
একটা RAG-ভিত্তিক assistant।
## Demo
 <-- একটা GIF হাজার শব্দের সমান
Live: https://... (থাকলে)
## Features
- 5k+ job description থেকে skill extraction
- RAG দিয়ে career Q&A (pgvector + LLM)
- FastAPI endpoint, Docker-ready
## Architecture
## Quickstart
```bash
git clone https://github.com/rahim/bd-tech-career-assistant
cd bd-tech-career-assistant
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # তারপর key বসান
uvicorn src.career_assistant.api:app --reload
```
## Results
| Metric | Value |
|---------------------|-------|
| Retrieval precision | 0.82 |
| API latency (p95) | 140ms |
## Tech stack
Python, Pandas, sentence-transformers, PostgreSQL/pgvector,
FastAPI, Docker
README-এ সবচেয়ে দামি দুটো জিনিস: (১) একটা demo GIF/screenshot (এক নজরে বোঝা যায়),
(২) একটা কাজ করা Quickstart (প্রমাণ করে এটা সত্যিই চলে)।
♻️ ৬. Reproducibility: "clone করে চালানো যায়" প্রমাণ
সবচেয়ে শক্তিশালী signal — অন্য কেউ তোমার repo clone করে, README ফলো করে, ঠিকঠাক চালাতে পারে। এর জন্য দরকার:
requirements.txtবাpyproject.toml— সঠিক dependency, version সহ (Series 02-এ শেখা).env.example— কোন কোন secret লাগবে তার template (আসল.envকখনো commit করবেন না)- data কোথা থেকে আসবে — download script বা link, কারণ বড় data repo-তে থাকবে না
- পরিষ্কার run instruction — এক-দুইটা command
⚠️ Secret leak: ভুল করে
.env বা API key commit করা AI/ML repo-তে খুব
common ভুল, এবং এটা একটা negative signal। সবসময় .gitignore-এ .env রাখুন,
আর accidentally commit হয়ে গেলে key rotate করুন — history থেকে মুছলেও ধরে নিতে হবে সেটা leaked।
🎬 ৭. Demo: দেখানো > বলা
একটা কাজ করা demo তোমার repo-কে বাকি ৯০% থেকে আলাদা করে। বিকল্পগুলো (সহজ থেকে কঠিন):
| Demo type | কীভাবে | কখন |
|---|---|---|
| Screenshot/GIF | terminal বা UI-এর ছবি/GIF README-তে | সবসময়, সবচেয়ে সহজ |
| Deployed link | FastAPI app cloud-এ (Series 09) | API/RAG project-এ দারুণ |
| Streamlit/Gradio demo | দ্রুত একটা UI বানিয়ে Hugging Face Spaces-এ host | ML/NLP demo-র জন্য জনপ্রিয় |
| Notebook (rendered) | GitHub নিজেই .ipynb render করে | EDA/analysis দেখাতে |
Must Know / Learn Later: চাকরির আগে অন্তত একটা GIF/screenshot অবশ্যই। একটা live
deployed demo থাকলে বড় plus, কিন্তু বাধ্যতামূলক নয় — সেটা পরে যোগ করা যায়।
🧪 ৮. Tests ও architecture diagram
অনেক junior test লেখে না, তাই একটা ছোট test suite থাকলেই তুমি আলাদা হয়ে যাও। কমপক্ষে একটা-দুটো
pytest test (Series 02-এ শেখা) দেখায় তুমি code quality নিয়ে ভাবো।
# tests/test_preprocess.py
from career_assistant.preprocess import extract_skills
def test_extract_skills_finds_python():
text = "Looking for Python and SQL experience."
skills = extract_skills(text)
assert "python" in skills
assert "sql" in skills
Architecture diagram-ও শক্তিশালী signal — এটা প্রমাণ করে তুমি system-level চিন্তা করতে পারো। জটিল tool দরকার নেই; একটা simple box-and-arrow ছবি (এমনকি ASCII) যথেষ্ট:
Job Descriptions ──► Preprocess ──► Embeddings ──► pgvector
│
User Question ──────────────► Retrieve top-k ◄─────────┘
│
▼
LLM + context ──► Answer
👤 ৯. GitHub profile ও pinned repo
Repo ঠিক করার পর profile-টাও গুরুত্বপূর্ণ। recruiter প্রথমে তোমার profile page দেখে। তাই:
- Pin করো তোমার সেরা ৩-৬টা repo (এলোমেলো ৫০টা নয়)
- একটা profile README (username নামের repo-তে) — ২-৩ লাইনে তুমি কে, কী করো
- পরিষ্কার bio + প্রতিটা pinned repo-তে ভালো description ও topics/tags
- পুরনো, অসম্পূর্ণ, embarrassing repo গুলো private করে দাও বা archive করো
💼 Boss Question
Boss: "এত সাজানো-গোছানো GitHub দিয়ে আমার business-এর কী লাভ? আমি তো coder চাই, decorator না।"
উত্তর: সাজানো repo মানে decoration নয় — এটা প্রমাণ যে এই লোকটা maintainable কোড লেখে। একটা কোম্পানিতে কোড শুধু একবার লেখা হয় না, বছরের পর বছর অন্যরা সেটা পড়ে, বদলায়, চালায়। যে junior আজ README আর test লিখতে অভ্যস্ত, সে team-এ যোগ দিলে অন্যদের সময় বাঁচায়, bug কমায় — সেটাই সরাসরি business value।
Boss: "এত সাজানো-গোছানো GitHub দিয়ে আমার business-এর কী লাভ? আমি তো coder চাই, decorator না।"
উত্তর: সাজানো repo মানে decoration নয় — এটা প্রমাণ যে এই লোকটা maintainable কোড লেখে। একটা কোম্পানিতে কোড শুধু একবার লেখা হয় না, বছরের পর বছর অন্যরা সেটা পড়ে, বদলায়, চালায়। যে junior আজ README আর test লিখতে অভ্যস্ত, সে team-এ যোগ দিলে অন্যদের সময় বাঁচায়, bug কমায় — সেটাই সরাসরি business value।
🔎 ১০. Job Requirement Decoder
JD-তে প্রায়ই থাকে: "Writes clean, well-documented, and maintainable code."
| প্রশ্ন | উত্তর |
|---|---|
| কী বোঝায়? | কোড শুধু চলে না — অন্যরা পড়ে বোঝে, চালাতে পারে, নিরাপদে বদলাতে পারে। |
| কেন চায়? | টিমে কোড বছরের পর বছর maintain হয়; খারাপ কোড দীর্ঘমেয়াদে ব্যয়বহুল। |
| কোন সমস্যা সমাধান করে? | onboarding সহজ, bug কম, "আমার মেশিনে চলছিল" সমস্যা কমে। |
| junior-এর কী জানা লাগে? | README, requirements, .gitignore, পরিষ্কার commit, ছোট test, notebook-vs-src পার্থক্য। |
| এখনই কী master লাগে না? | জটিল CI/CD pipeline, ১০০% test coverage, monorepo tooling। |
| GitHub-এ কীভাবে দেখাবে? | এই পুরো episode-ই তার উত্তর — পরিষ্কার repo + README + demo + test। |
| Interview-তে কী জিজ্ঞেস করতে পারে? | "এই repo-টা আমাকে চালিয়ে দেখাও তো", "কেন notebook আর src আলাদা রাখলে?" |
⚠️ ১১. সাধারণ ভুল
ভুল ১: README নেই বা default। → ঠিক: problem, quickstart, demo, results সহ README।
ভুল ২: শুধু একটা বিশাল notebook। → ঠিক: reusable code
ভুল ৩: বড় data/model repo-তে push। → ঠিক: gitignore করুন; link/release ব্যবহার করুন।
ভুল ৪:
ভুল ৫: "asdf", "final v3" এর মতো commit message। → ঠিক: অর্থপূর্ণ message (Series 02 Git পর্ব)।
ভুল ৬: ৫০টা অসম্পূর্ণ repo pin করা। → ঠিক: সেরা ৩-৬টা pin, বাকিটা গুছিয়ে ফেলুন।
ভুল ২: শুধু একটা বিশাল notebook। → ঠিক: reusable code
src/-এ সরান।ভুল ৩: বড় data/model repo-তে push। → ঠিক: gitignore করুন; link/release ব্যবহার করুন।
ভুল ৪:
.env/API key commit। → ঠিক: gitignore + .env.example; leak হলে key rotate।ভুল ৫: "asdf", "final v3" এর মতো commit message। → ঠিক: অর্থপূর্ণ message (Series 02 Git পর্ব)।
ভুল ৬: ৫০টা অসম্পূর্ণ repo pin করা। → ঠিক: সেরা ৩-৬টা pin, বাকিটা গুছিয়ে ফেলুন।
🎤 ১২. Interview Prep
প্রশ্ন ১: তোমার এই repo-টা কীভাবে structure করেছ, আর কেন?
উত্তর: notebook (exploration) বনাম src (reusable code) পার্থক্য, README-র ভূমিকা, reproducibility।
প্রশ্ন ২: এই project কেউ clone করে চালাতে চাইলে কী করবে?
উত্তর: Quickstart ধাপ দেখাও — venv, requirements, .env, run command। চালিয়ে দেখাতে পারলে দারুণ।
প্রশ্ন ৩: Test লিখেছ? কেন গুরুত্বপূর্ণ?
উত্তর: preprocess/utility function-এ test দেখায় regression ধরা যায়; refactor করার সাহস বাড়ে।
উত্তর: notebook (exploration) বনাম src (reusable code) পার্থক্য, README-র ভূমিকা, reproducibility।
প্রশ্ন ২: এই project কেউ clone করে চালাতে চাইলে কী করবে?
উত্তর: Quickstart ধাপ দেখাও — venv, requirements, .env, run command। চালিয়ে দেখাতে পারলে দারুণ।
প্রশ্ন ৩: Test লিখেছ? কেন গুরুত্বপূর্ণ?
উত্তর: preprocess/utility function-এ test দেখায় regression ধরা যায়; refactor করার সাহস বাড়ে।
✍️ ১৩. হাতে-কলমে (Mini Exercise)
তোমার সেরা project-টা নিয়ে আজই এই checklist সম্পন্ন করো:
☐ একটা README লেখো: এক লাইন description, Quickstart, একটা screenshot/GIF, results table
☐
☐
☐ অন্তত একটা
☐ একটা simple architecture diagram (ASCII হলেও চলবে) যোগ করো
☐ GitHub profile-এ এই repo pin করো
☐ একটা README লেখো: এক লাইন description, Quickstart, একটা screenshot/GIF, results table
☐
requirements.txt আর .gitignore যোগ করো☐
.env বা কোনো secret commit করা আছে কিনা চেক করো — থাকলে সরাও☐ অন্তত একটা
pytest test লেখো☐ একটা simple architecture diagram (ASCII হলেও চলবে) যোগ করো
☐ GitHub profile-এ এই repo pin করো
🚀 ১৪. Project Connection
Flagship "Bangladesh Tech Career Assistant"-কে এই episode-এর checklist দিয়ে সাজালে
এটা তোমার portfolio-র মুকুট হয়ে যাবে। Series 09-এ আমরা এটাকে notebook থেকে src/ package,
FastAPI, Docker-এ রূপান্তর করেছি — সেই structure-ই এখানে repo হিসেবে দেখানোর জন্য প্রস্তুত। README-তে
সেই "notebook → production" যাত্রাটা দেখালে recruiter বুঝবে তুমি পুরো lifecycle সামলাতে পারো।
📌 ১৫. সারসংক্ষেপ
এই Episode-এ আমরা শিখলাম:
✓ junior-এর জন্য GitHub-ই আসল CV — বলা নয়, দেখানো
✓ Repo structure: notebook (exploration) বনাম src (reusable code) আলাদা
✓ README-ই repo-র হৃদয়: problem, quickstart, demo GIF, results
✓ Reproducibility: requirements, .env.example, clear run steps — secret কখনো commit নয়
✓ Demo (GIF/deployed/Streamlit) তোমাকে ৯০% থেকে আলাদা করে
✓ ছোট test suite + architecture diagram = engineer signal
✓ Profile-এ সেরা ৩-৬টা repo pin, বাকিটা গুছিয়ে রাখা
✓ junior-এর জন্য GitHub-ই আসল CV — বলা নয়, দেখানো
✓ Repo structure: notebook (exploration) বনাম src (reusable code) আলাদা
✓ README-ই repo-র হৃদয়: problem, quickstart, demo GIF, results
✓ Reproducibility: requirements, .env.example, clear run steps — secret কখনো commit নয়
✓ Demo (GIF/deployed/Streamlit) তোমাকে ৯০% থেকে আলাদা করে
✓ ছোট test suite + architecture diagram = engineer signal
✓ Profile-এ সেরা ৩-৬টা repo pin, বাকিটা গুছিয়ে রাখা
➡️ ১৬. পরবর্তী পর্বে কী শিখব
পরবর্তী Episode (S10E03): "Portfolio Strategy: ৫টা project যা junior থেকে আলাদা করে"।
Repo সাজানো শিখলাম — কিন্তু কোন project গুলো বানাব? পরের পর্বে দেখব কীভাবে Classical ML, Deep Learning, NLP/LLM, RAG আর Production — এই ৫ ধরনের project দিয়ে একটা coherent, differentiating portfolio সাজাতে হয়।
Repo সাজানো শিখলাম — কিন্তু কোন project গুলো বানাব? পরের পর্বে দেখব কীভাবে Classical ML, Deep Learning, NLP/LLM, RAG আর Production — এই ৫ ধরনের project দিয়ে একটা coherent, differentiating portfolio সাজাতে হয়।
📖 ডকুমেন্ট তথ্য
সংস্করণ: ১.০ • ভাষা: বাংলা
সিরিজ: AI/ML Engineer বাংলা সিরিজ — Zero to Job-Ready (Series 10, Episode 02)
লেখক: Sheikh Thanbir Alam
👁️ পাতাটি দেখা হয়েছে: 