Tổng Quan Dự Án Learn Tanhdev & Tiêu Chuẩn Xuất Bản

Dự án learn.tanhdev.com là nền tảng xuất bản tri thức kỹ thuật chuyên sâu, tập trung vào kiến trúc hệ thống phân tán, Go backend engineering, microservices patterns, hạ tầng AI và tối ưu hóa hiệu năng sản xuất (Production Performance Optimization).

Tài liệu này trình bày chi tiết về cấu trúc theme Hugo Book, quy trình ghi nhận quyết định kiến trúc (ADRs), các tiêu chuẩn tổ chức nội dung và hướng dẫn đóng góp bài viết cho nền tảng.

1. Cấu Trúc Theme Hugo Book & Layout Hệ Thống

Trang web learn.tanhdev.com sử dụng Hugo (máy phát sinh trang tĩnh - Static Site Generator siêu tốc) làm core engine cùng theme Hugo Book đã qua tinh chỉnh để tối ưu hóa khả năng hiển thị tài liệu kỹ thuật nhiều tầng.

1.1. Cấu Trúc Thư Mục Nội Dung (/content)

  • /content/docs/: Khu vực lưu trữ tài liệu kỹ thuật dạng sách (Book layout).
    • _index.md: Trang mục lục chính cho toàn bộ khu vực tài liệu kiến trúc.
    • overview.md: Trang tổng quan về kiến trúc và tiêu chuẩn xuất bản dự án.
    • affiliate-website-report.md: Báo cáo thực nghiệm chuyên sâu về kiến trúc website affiliate & caching.
  • /content/posts/: Nơi xuất bản các bài viết phân tích kỹ thuật, bài hướng dẫn (Tutorials) và bài nghiên cứu điển hình (Case Studies).
  • /content/newsletter.md, /content/privacy-policy.md: Các trang thông tin tĩnh và chính sách hệ thống.

1.2. Tính Năng & Cấu Hình Hugo Book Theme

Theme Hugo Book hỗ trợ các tính năng cốt lõi cho tài liệu kỹ thuật:

  • Collapsible Menu System (bookCollapseSection): Tự động gộp/mở các mục tài liệu phức tạp giúp người đọc tập trung vào nhánh nội dung cần thiết.
  • Table of Contents (TOC): Sinh tự động mục lục bên phải trang dựa trên các thẻ tiêu đề (H2, H3).
  • Code Block Formatting & Syntax Highlighting: Hỗ trợ tô màu cú pháp chuẩn cho Go, Python, Yaml, Dockerfile, SQL, Bash…
  • Shortcodes Tùy Biến: Hỗ trợ hiển thị ghi chú ({{< hint info >}}), tab mã nguồn ({{< tabs >}}), và nút tương tác ({{< button >}}).

2. Quy Trình Ghi Nhận Quyết Định Kiến Trúc (ADR - Architectural Decision Record)

Để quản lý lịch sử tiến hóa kiến trúc của các dự án tại learn.tanhdev.com, mọi thay đổi kiến trúc quan trọng đều phải được ghi vết dưới dạng Architectural Decision Record (ADR).

2.1. Cấu Trúc Chuẩn Của Một Bản ADR

Mỗi tài liệu ADR tuân thủ mẫu chuẩn gồm 5 phần chính:

  1. Title & Status (Tiêu đề & Trạng thái):
    • Trạng thái: Proposed (Đề xuất), Accepted (Đã duyệt), Deprecated (Không còn dùng), hoặc Superseded (Thay thế bởi ADR-xxx).
  2. Context & Problem Statement (Bối cảnh & Vấn đề):
    • Mô tả yêu cầu bài toán kỹ thuật, thách thức về băng thông, độ trễ hoặc khả năng mở rộng.
  3. Decision Drivers (Yếu tố quyết định):
    • Chi phí hạ tầng, khả năng bảo trì, kinh nghiệm đội ngũ, tính tương thích sinh thái (Go, gRPC, Cloud Native).
  4. Considered Options (Các phương án được cân nhắc):
    • Liệt kê các giải pháp thay thế (ví dụ: REST vs gRPC, Redis vs Memcached, RabbitMQ vs Kafka) kèm phân tích ưu/nhược điểm.
  5. Decision & Consequences (Quyết định & Hậu quả):
    • Giải pháp được chọn và phân tích tác động tích cực/tiêu cực sau khi áp dụng.

3. Tiêu Chuẩn Tổ Chức Nội Dung (Content Standards)

Tất cả các bài viết và tài liệu xuất bản trên learn.tanhdev.com bắt buộc phải tuân thủ các quy chuẩn trình bày nhằm bảo đảm tính chuyên nghiệp và dễ đọc:

3.1. Quy Chuẩn Frontmatter (YAML Header)

Mỗi file Markdown phải chứa phần khai báo thuộc tính hoàn chỉnh:

---
title: "Tên Bài Viết Viết Hoa Các Chữ Cái Đầu"
slug: "chu-de-bai-viet-slug-kebab-case"
date: 2026-07-25T12:00:00+07:00
lastmod: 2026-07-25T12:00:00+07:00
draft: false
description: "Mô tả ngắn gọn (120-160 ký tự), súc tích, chuẩn SEO thể hiện chính xác nội dung cốt lõi."
categories: ["Microservices", "Golang"]
tags: ["gRPC", "DDD", "High Performance"]
ShowToc: true
TocOpen: true
---

3.2. Tiêu Chuẩn Định Dạng Markdown

  • Phân cấp tiêu đề (Heading Hierarchy):
    • Header # H1 được Hugo render tự động từ title trong frontmatter.
    • Nội dung bài viết bắt đầu bằng ## H2 cho các phần chính, ### H3 cho các mục con. Không sử dụng # H1 trực tiếp trong Markdown body.
  • Mã Nguồn (Code Blocks):
    • Khai báo rõ ngôn ngữ lập trình (ví dụ: go ... , bash ... ).
    • Đặt tên file hoặc ghi chú ngữ cảnh lên đầu đoạn code nếu cần thiết.
  • Hình Ảnh & Sơ Đồ Kiến Trúc:
    • Lưu ảnh tại thư mục /static/images/ hoặc asset co-located.
    • Sử dụng định dạng PNG/SVG nét cao kèm Alt Text rõ ràng.

4. Hướng Dẫn Đóng Góp (Contribution Guide)

Chúng tôi hoan nghênh mọi đóng góp từ cộng đồng lập trình viên và kỹ sư hệ thống. Quy trình đóng góp bài viết được thực hiện qua GitHub Workflow:

4.1. Cài Đặt Môi Trường Địa Phương (Local Setup)

  1. Clone repository về máy cá nhân:
    git clone https://github.com/vesviet/learn.tanhdev.com.git
cd learn.tanhdev.com
  2. Thêm hoặc cập nhật Git Submodules (đối với Hugo Themes):
    git submodule update --init --recursive
  3. Chạy môi trường xem trước (Local Server):
    hugo server -D --enableFastRender
    Truy cập http://localhost:1313/ để kiểm tra kết quả hiển thị real-time.

4.2. Quy Trình Tạo Bài Viết Mới (Creation & Review Workflow)

  1. Tạo file nội dung mới trong thư mục tương ứng:
    hugo new posts/my-new-architecture-post.md
# Hoặc tạo tài liệu trong docs/
  2. Soạn thảo nội dung và kiểm tra độ bao phủ tiêu chí (Checklist):
    • Frontmatter đầy đủ title, slug, description, tags.
    • Đã kiểm tra lỗi chính tả và định dạng Markdown.
    • Không vi phạm H1 hierarchy trong body bài viết.
    • Code ví dụ đã được test biên dịch thành công.
  3. Tạo Pull Request (PR) gửi về nhánh main và chờ phản hồi từ reviewer.

Cảm ơn bạn đã đóng góp xây dựng cộng đồng kiến trúc hệ thống bền vững tại learn.tanhdev.com!