Bài 18: Thêm demo GIF / screenshot vào README

Sau bài này bạn có thể:

• ✅ Chọn đúng loại visual (GIF, screenshot, diagram) cho từng mục đích.
• ✅ Record GIF demo trên macOS, Windows, Linux.
• ✅ Tối ưu file size GIF xuống dưới 5 MB bằng gifsicle.
• ✅ Nhúng GIF / screenshot / Mermaid diagram vào README đúng cú pháp.
• ✅ Tránh các anti-pattern phổ biến (GIF quá to, chứa thông tin nhạy cảm, quality thấp).

Recruiter và người review GitHub thường scan README trong khoảng 30 giây trước khi quyết định đọc tiếp hay không. Văn bản thuần túy không truyền tải được product đang làm gì; ảnh / GIF demo thì truyền tải ngay lập tức.

Cụ thể hơn:

• GIF loop tự động — người xem thấy product chạy mà không cần click hay cài đặt gì.
• Screenshot dashboard — show UI/UX sau 1 nhìn, không cần đọc mô tả dài.
• Architecture diagram — recruiter kỹ thuật đánh giá độ sâu thiết kế ngay trong vài giây.
• Confusion matrix / learning curve — chứng minh bạn đã đánh giá model đúng cách.

Project có visual thường nhận nhiều interaction hơn so với project chỉ có text — không phải vì ảnh "đẹp" mà vì nó giảm friction cho người đọc.

a) Screenshot — đơn giản nhất

• Ảnh tĩnh, thể hiện 1 trạng thái cụ thể (dashboard, kết quả prediction, UI).
• Format: PNG (lossless, tốt cho UI có text) hoặc JPG (nhỏ hơn, phù hợp ảnh chụp màn hình chứa nhiều màu).
• Phù hợp khi product không có animation hoặc interaction cần show.

b) GIF — recommended cho demo flow

• Loop tự động, show interaction end-to-end: input → process → output.
• Độ dài lý tưởng: 5–15 giây. Dài hơn thường bị skip.
• File size target: 1–5 MB. Trên 10 MB GitHub không render inline.

c) Video — cho project phức tạp

• 30 giây đến 2 phút — phù hợp demo có nhiều flow khác nhau.
• GitHub README không tự play video inline → cần link ra Loom hoặc YouTube.
• Bài 20 đề cập chi tiết workflow tạo video demo.

macOS

• Kap (free, open source) — record màn hình, export trực tiếp ra GIF hoặc MP4. Giao diện đơn giản, đủ dùng cho phần lớn trường hợp. Download tại getkap.co.
• CleanShot X (trả phí, $29 lifetime) — nhiều tính năng hơn: scrolling capture, annotation, cloud upload.
• Gifox (trả phí) — tập trung vào GIF, có crop window tiện lợi.
• QuickTime + ffmpeg — built-in macOS + CLI. Xem phần 7 để biết lệnh convert.

Windows

• ScreenToGif (free, open source) — record screen hoặc webcam, edit frame trực tiếp, tối ưu GIF built-in. Được dùng rộng rãi.
• LICEcap (free) — minimal, chỉ record và export GIF, không có editor.
• OBS Studio + ffmpeg — record MP4 rồi convert, phù hợp khi cần quality cao.

Linux

• Peek (free) — GUI đơn giản, record vùng chọn và export GIF. Cài qua package manager phần lớn distro.
• OBS Studio + ffmpeg — tương tự Windows.

Web / cross-platform

• EzGif.com — convert MP4 → GIF online, optimize GIF trực tiếp trên browser. Không cần cài đặt.
• Loom (free tier: tối đa 25 video, mỗi video 5 phút) — record và chia sẻ link. Lưu ý: Loom free không export GIF, chỉ cho link video.

Bước 1: Lên kịch bản (2–3 phút chuẩn bị)

Xác định user flow cụ thể, 3–5 bước ngắn. Ví dụ với RAG chatbot:

1. Mở app trên browser.
2. Gõ câu hỏi vào input.
3. Xem câu trả lời kèm source citation.
4. Click expand để đọc đoạn trích dẫn.

Tránh thêm bước không cần thiết: random click, di chuyển chuột vô nghĩa, mở menu rồi đóng lại.

Bước 2: Setup môi trường sạch

• Đổi desktop background sang màu trơn (tránh ảnh cá nhân lộ trong GIF).
• Tắt hoặc ẩn notification: Slack, mail, calendar reminder.
• Dùng incognito/private browser window để không có bookmark bar, extension icon lộn xộn.
• Resize window về kích thước cố định: 1280×720 hoặc 1600×900. Tránh full screen nếu không cần.

Bước 3: Record

• Frame rate: 15 FPS là đủ cho hầu hết GIF demo (file nhỏ hơn so với 30 FPS), 30 FPS dùng khi animation cần mượt.
• Resolution: 800–1200 px width là đủ để đọc được text trong GIF trên GitHub.
• Quay một đoạn dài hơn cần thiết rồi cắt — tránh quay nhiều take.
• Bật hiển thị con trỏ chuột (option trong tool) để người xem theo dõi được.

Bước 4: Edit

• Trim đầu cuối: bỏ đoạn chờ app load, bỏ đoạn chuột đang di chuyển đến vị trí bắt đầu.
• Speed up đoạn chờ dài: nếu model cần 5 giây để generate → speed 4× để GIF không bị đơ.
• Loop seamless: frame cuối nên gần giống frame đầu (ví dụ quay về màn hình input trống).
• Caption overlay: chỉ thêm nếu thực sự cần giải thích — tránh text quá dày.

Bước 5: Verify trước khi commit

• Xem lại GIF: không có thông tin nhạy cảm (API key trong terminal, email user, password).
• Kiểm tra file size: nếu vượt 5 MB → chạy gifsicle (xem bước 6).
• Aspect ratio đúng: không bị méo khi embed vào README.

gifsicle là CLI tool tối ưu GIF — giảm số màu, loại bỏ frame dư thừa, resize.

Cài đặt

# macOS
brew install gifsicle

# Ubuntu / Debian
sudo apt install gifsicle

# Windows — dùng Chocolatey
choco install gifsicle

Lệnh cơ bản

# Tối ưu level cao nhất (-O3) + giảm xuống 128 màu
gifsicle -O3 --colors 128 input.gif -o output.gif

# Resize xuống 800px width, giữ aspect ratio
gifsicle --resize-width 800 input.gif -o output.gif

# Kết hợp: resize + optimize + giảm màu
gifsicle -O3 --colors 128 --resize-width 800 input.gif -o output.gif

Guideline file size

• Dưới 2 MB: tốt, load nhanh kể cả kết nối chậm.
• 2–5 MB: chấp nhận được.
• 5–10 MB: GitHub vẫn render nhưng load chậm — nên tối ưu thêm.
• Trên 10 MB: GitHub không render inline — chỉ hiển thị link. Cần resize hoặc cắt ngắn GIF.

Kiểm tra kết quả

# So sánh trước / sau
ls -lh input.gif output.gif

Thông thường -O3 --colors 128 giảm được 30–60% file size mà chất lượng visual vẫn đủ dùng.

Khi record bằng QuickTime (macOS) hoặc OBS Studio, file output là MP4/MOV. Có thể convert sang GIF bằng ffmpeg với palette tối ưu để giữ chất lượng màu tốt hơn convert thẳng.

Cài đặt ffmpeg

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

Convert cơ bản (1 lệnh)

ffmpeg -i input.mov \
  -vf "fps=15,scale=800:-1:flags=lanczos" \
  -c:v gif output.gif

Giải thích các tham số:

• fps=15 — giảm frame rate xuống 15 FPS.
• scale=800:-1 — resize width 800px, height tự tính theo aspect ratio.
• flags=lanczos — thuật toán resampling chất lượng cao khi scale.

Convert 2 pass với palette (chất lượng màu tốt hơn)

# Pass 1: tạo palette màu tối ưu cho video cụ thể
ffmpeg -i input.mov \
  -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" \
  palette.png

# Pass 2: convert với palette vừa tạo
ffmpeg -i input.mov -i palette.png \
  -filter_complex "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" \
  output.gif

2-pass method cho GIF màu sắc trung thực hơn, đặc biệt rõ sự khác biệt với UI có gradient hoặc màu tối.

Trim trước khi convert

# Chỉ lấy từ giây 3 đến giây 18 (15 giây)
ffmpeg -ss 3 -t 15 -i input.mov \
  -vf "fps=15,scale=800:-1:flags=lanczos" \
  -c:v gif output.gif

Cấu trúc thư mục khuyến nghị

your-project/
├── docs/
│   └── images/
│       ├── demo.gif
│       ├── architecture.png
│       └── confusion_matrix.png
├── README.md
└── ...

Lưu file ảnh trong docs/images/ thay vì root repo để giữ cấu trúc gọn gàng.

Cú pháp Markdown

![Demo](docs/images/demo.gif)

![Architecture](docs/images/architecture.png)

GitHub render GIF inline tự động khi path đúng. Alt text (Demo, Architecture) là bắt buộc cho accessibility — không để trống.

Thêm caption

![Demo RAG chatbot — hỏi đáp tài liệu PDF nội bộ](docs/images/demo.gif)

Upload ảnh qua GitHub Issues (alternative)

Cách này tránh bloat repo size:

1. Tạo hoặc mở 1 Issue bất kỳ trên repo.
2. Kéo thả file ảnh / GIF vào ô comment.
3. GitHub upload và generate CDN URL dạng https://user-images.githubusercontent.com/....
4. Copy URL đó vào README.

Lưu ý: CDN URL từ GitHub Issues là public và không hết hạn theo policy hiện tại, nhưng phụ thuộc vào chính sách GitHub. Lưu trong repo là cách bền vững hơn về dài hạn.

Công cụ chụp screenshot

• macOS: Cmd+Shift+4 (chụp vùng chọn), Cmd+Shift+5 (menu đầy đủ với tùy chọn). Ảnh lưu Desktop mặc định.
• Windows: Win+Shift+S (Snipping Tool), Print Screen (toàn màn hình vào clipboard).
• Linux: gnome-screenshot, flameshot (có annotation).

Best practice

• Crop sát nội dung: chỉ capture vùng liên quan, không chụp cả desktop với dock / taskbar.
• Annotation tối giản: nếu cần highlight, dùng arrow đỏ hoặc box — không dùng nhiều màu lộn xộn.
• Không có thông tin nhạy cảm: che API key, email, tên thật user nếu đang dùng data thật.
• Consistent resolution: nếu có nhiều screenshot trong cùng README, dùng cùng độ rộng để trông đồng đều.
• PNG cho UI text-heavy, JPG cho ảnh chứa nhiều màu (chart, photo). PNG thường sắc nét hơn cho screenshot.

Tool annotation

• macOS: Preview (built-in) — đủ dùng cho arrow và box đơn giản.
• Skitch (Evernote, free): arrow, highlight, blur nhanh.
• Greenshot (Windows, free): chụp + annotate trong 1 workflow.

Architecture diagram giúp người đọc hiểu nhanh cách các thành phần kết nối với nhau — quan trọng với project AI có nhiều service.

Excalidraw (free, recommended)

Tạo diagram theo phong cách hand-drawn, trông tự nhiên hơn diagram formal. Export PNG hoặc SVG. Lưu file .excalidraw vào repo để chỉnh sửa sau.

• Web: excalidraw.com
• VS Code extension: pomdtr.excalidraw-editor

draw.io / diagrams.net (free)

Formal box diagram với nhiều shape library. Export PNG/SVG, file lưu XML. Tích hợp Google Drive và VS Code.

Mermaid — diagram từ code (version control friendly)

GitHub render Mermaid diagram trực tiếp trong Markdown, không cần ảnh tĩnh. Diagram được version control cùng code.

```mermaid
flowchart LR
    A[User] --> B[FastAPI]
    B --> C[ChromaDB]
    C --> B
    B --> D[OpenAI GPT-4o]
    D --> B
    B --> A
```

Kết quả: GitHub tự render thành flow chart khi xem README. Mermaid hỗ trợ nhiều loại diagram: flowchart, sequence diagram, ER diagram, Gantt chart.

Khi nào dùng gì:

• Mermaid — diagram đơn giản, muốn version control, không cần ảnh đẹp.
• Excalidraw — diagram có nhiều component, muốn cá nhân hóa visual.
• draw.io — cần share với team không quen Mermaid syntax.

Đây là phần visual ít người làm nhưng có giá trị cao với recruiter kỹ thuật — chứng minh bạn đã evaluate model đúng cách.

Xuất chart từ matplotlib / seaborn

import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.metrics import confusion_matrix, ConfusionMatrixDisplay

# Ví dụ: vẽ confusion matrix
cm = confusion_matrix(y_true, y_pred)
disp = ConfusionMatrixDisplay(confusion_matrix=cm, display_labels=class_names)

fig, ax = plt.subplots(figsize=(8, 6))
disp.plot(ax=ax, colorbar=False, cmap="Blues")
ax.set_title("Confusion Matrix — Test Set", fontsize=13)

plt.tight_layout()
plt.savefig("docs/images/confusion_matrix.png", dpi=150, bbox_inches="tight")
plt.close()

Tham số quan trọng:

• dpi=150 — đủ sắc nét khi render trên README, không quá nặng như dpi=300.
• bbox_inches="tight" — loại bỏ whitespace thừa xung quanh figure.
• plt.close() — giải phóng memory trong notebook nếu loop nhiều chart.

Các chart nên có trong README (tùy project)

• Classification: confusion matrix, ROC curve, precision-recall curve.
• Regression: actual vs predicted scatter plot, residual plot.
• Training: loss curve / accuracy curve theo epoch.
• Data: class distribution chart để show data imbalance nếu có.

Style nhất quán

import matplotlib.pyplot as plt

# Set style 1 lần ở đầu notebook
plt.rcParams.update({
    "figure.dpi": 100,
    "font.size": 11,
    "axes.titlesize": 13,
    "axes.labelsize": 11,
    "figure.facecolor": "white",
})

Tất cả chart trong project sẽ dùng chung style, trông đồng nhất trong README.

GitHub giới hạn file tối đa 100 MB, repo khuyến nghị dưới 1 GB. GIF lớn làm git clone chậm hơn đáng kể.

Ngưỡng thực tế

• GIF dưới 5 MB: commit thẳng vào repo — không cần LFS.
• GIF 5–10 MB: cân nhắc tối ưu bằng gifsicle trước.
• File trên 10 MB: dùng Git LFS hoặc host bên ngoài.

Git LFS — khi cần thiết

# Cài Git LFS
git lfs install

# Track file GIF lớn
git lfs track "*.gif"

# File .gitattributes được tạo tự động
git add .gitattributes
git add docs/images/demo-large.gif
git commit -m "docs: add demo gif via LFS"

Lưu ý: GitHub free plan có 1 GB LFS storage và 1 GB/tháng bandwidth. Dùng thật sự cần thiết mới track qua LFS.

Thứ tự ưu tiên để giảm file size

1. Cắt ngắn GIF (5–10 giây thay vì 20–30 giây).
2. Giảm resolution (800px width thường đủ).
3. Giảm FPS xuống 15.
4. Chạy gifsicle -O3 --colors 128.
5. Nếu vẫn > 10 MB: chuyển sang dùng link video (Loom / YouTube).

Thứ tự visual trong README ảnh hưởng đến ấn tượng đầu tiên:

1. GIF demo chính — đặt ngay sau title + tagline, trước bất kỳ mô tả nào. Đây là visual quan trọng nhất.
2. Architecture diagram — đặt trước hoặc ngay sau phần "Quick Start". Recruiter kỹ thuật đọc đây sớm.
3. Results / metrics chart — đặt trong section "Results" hoặc "Performance". Confusion matrix, learning curve đi ở đây.
4. Screenshot chi tiết UI — đặt trong section "Features" nếu cần show nhiều view khác nhau.

Nguyên tắc: mỗi section quan trọng tối đa 1–2 visual. Nhiều hơn làm README nặng và phân tán.

Ví dụ cấu trúc đơn giản

# RAG Chatbot

> Q&A trên tài liệu PDF nội bộ sử dụng LangChain + ChromaDB + GPT-4o.

![Demo](docs/images/demo.gif)

## Architecture

```mermaid
flowchart LR
    A[User] --> B[FastAPI]
    B --> C[ChromaDB]
    B --> D[OpenAI]
    D --> B
    B --> A
```

## Quick Start
...

## Results

| Metric | Score |
|--------|-------|
| Faithfulness | 0.87 |
| Answer Relevancy | 0.91 |

![Ragas evaluation](docs/images/ragas_scores.png)

GIF

• GIF quá dài: 30 giây với 5 giây "loading" ở giữa → người xem bỏ qua. Cắt xuống còn phần interaction thực sự.
• Quality quá thấp: compress quá mạnh làm text trong GIF không đọc được → mất giá trị.
• Chứa thông tin nhạy cảm: API key lộ trong terminal, email user thật, token trong URL bar. Phải kiểm tra kỹ trước khi commit.
• GIF > 50 MB trong repo: làm clone chậm, người dùng khó contribute. Tối ưu hoặc dùng LFS.
• Reuse GIF từ project khác: GIF không khớp với code hiện tại → confusing.
• Quên cập nhật GIF khi code thay đổi: UI demo khác với code trong repo → mismatch.

Screenshot

• Chụp cả desktop: dock, taskbar, đồng hồ, notification badge lộ → distracting, không professional.
• Alt text trống: ![](docs/images/demo.png) — kém accessibility, SEO cũng kém hơn.
• Annotation quá nhiều: 10 mũi tên đỏ trên 1 screenshot → rối mắt hơn là helpful.

Architecture diagram

• Quá nhiều box: diagram 40–50 component không readable trên README — chia nhỏ hoặc show chỉ high-level.
• Không có label rõ ràng: box chỉ ghi "Service A" → không có thông tin.
• Dùng ảnh screenshot của draw.io thay vì export clean: kèm theo title bar, border, background không mong muốn.

• ✅ GIF demo (5–15 giây, dưới 5 MB) đặt ngay sau title — loại visual có impact cao nhất trong README.
• ✅ macOS: dùng Kap (free). Windows: ScreenToGif (free). Linux: Peek hoặc OBS + ffmpeg.
• ✅ Quy trình 5 bước: plan kịch bản → setup môi trường → record → edit → verify.
• ✅ Tối ưu file size bằng gifsicle -O3 --colors 128; convert MP4 → GIF bằng ffmpeg với palette 2-pass.
• ✅ Lưu ảnh trong docs/images/, nhúng bằng ![alt](path) có alt text đầy đủ.
• ✅ Architecture diagram: dùng Mermaid cho diagram đơn giản (version control friendly), Excalidraw cho diagram phức tạp hơn.
• ✅ Chart từ notebook: plt.savefig("docs/images/...", dpi=150, bbox_inches="tight").
• ✅ Không commit GIF > 10 MB; không để thông tin nhạy cảm lộ trong ảnh.

Bài 19: Viết blog post giải thích project — Medium / Dev.to / blog cá nhân