Chuyển tới nội dung chính

Contributing Guide

Cảm ơn bạn đã đóng góp cho CommitToMemory! Hướng dẫn này bao gồm mọi thứ bạn cần để viết và đóng góp nội dung chất lượng.

Prerequisites (Điều kiện tiên quyết)​

  • Node.js >= 20.0
  • Tài khoản GitHub
  • Quen thuộc cơ bản với Markdown

Quick Start (Bắt đầu nhanh)​

# 1. Fork and clone the repository (Fork và clone repository)
git clone https://github.com/<your-username>/CommitToMemory.git
cd CommitToMemory

# 2. Install dependencies (Cài đặt dependencies)
npm install

# 3. Start the dev server (Khởi động dev server)
npm start

Truy cập http://localhost:3000 để xem trước các thay đổi.

Where to Add Content (Nơi thêm nội dung)​

Chọn đúng directory dựa trên chủ đề:

DirectoryCategoryExample Topics
docs/intro/Introduction (Giới thiệu)Thông tin dự án, hướng dẫn
docs/cs/Computer Science (Khoa học Máy tính)Cấu trúc dữ liệu, thuật toán
docs/dotnet/.NET PlatformC#, LINQ, EF Core, async/await
docs/dotnet/csharp/C# Language (Ngôn ngữ C#)Chủ đề con về C#
docs/architecture/Architecture & Design (Kiến trúc & Thiết kế)SOLID, design patterns, DDD
docs/database/Database (Cơ sở dữ liệu)SQL, PostgreSQL, MongoDB, Redis
docs/system-design/System Design (Thiết kế hệ thống)Khả năng mở rộng, caching, message broker
docs/devops/DevOps & ToolingDocker, Git
docs/testing/Testing (Kiểm thử)xUnit, NUnit, mocking
mẹo

Khi không chắc chắn, hãy xem sidebars.ts để biết các chủ đề hiện tại được tổ chức như thế nào.

Step-by-Step: Add a New Topic (Từng bước: Thêm chủ đề mới)​

0. Chuẩn bị nguồn dữ liệu​

Trước khi viết, hãy thu thập và xem xét tài liệu tham khảo. Việc chọn nguồn đáng tin cậy, có thẩm quyền là rất quan trọng — chất lượng nội dung phụ thuộc trực tiếp vào chất lượng nguồn.

Các loại nguồn được khuyến nghị:

Loại nguồnVí dụĐộ tin cậy
Official documentation (Tài liệu chính thức)Microsoft Learn, MDN, PostgreSQL docsCao nhất
Foundational books (Sách nền tảng)CLR via C#, Designing Data-Intensive ApplicationsCao
Authoritative blogs (Blog uy tín)Martin Fowler, Microsoft Engineering, Stack Overflow BlogCao
RFCs & specifications (Thông số kỹ thuật)HTTP RFCs, ngôn ngữ specsCao
Community content (Nội dung cộng đồng)Medium articles, dev.to, RedditTrung bình — cần xác minh
Đánh giá nguồn của bạn
  • Ưu tiên primary source (nguồn gốc) (tài liệu chính thức, specs) hơn tóm tắt thứ cấp.
  • Cross-reference (tham khảo chéo) các nhận định từ nội dung cộng đồng với tài liệu chính thức.
  • Kiểm tra ngày xuất bản — nguồn cũ có thể mô tả các API hoặc pattern đã lỗi thời.
  • Đưa tất cả nguồn bạn đã sử dụng vào phần References (Tài liệu tham khảo) của chủ đề.
Tránh nguồn không đáng tin cậy
  • Bài blog không rõ tác giả hoặc nội dung AI tạo ra mà không được xác minh.
  • Câu trả lời Stack Overflow không có upvote hoặc chưa được chấp nhận.
  • Tài liệu cho phiên bản khác với phiên bản mà chủ đề đang đề cập.

1. Tạo file Markdown​

Tạo một file .md trong docs/ subdirectory phù hợp.

2. Thêm frontmatter​

Mỗi file bắt buộc phải bắt đầu với block frontmatter sau:

---
slug: /category/topic-name
title: Full Display Title
sidebar_label: Short Name
description: Mô tả SEO ngắn gọn (dưới 160 ký tự)
---

Quy tắc:

  • slug phải duy nhất trên toàn site và sử dụng kebab-case.
  • sidebar_label nên ngắn (lý tưởng dưới 20 ký tự) để sidebar dễ đọc.
  • description nên tóm tắt chủ đề trong một câu.

3. Viết nội dung sử dụng standard template​

Sử dụng cấu trúc sau để tất cả chủ đề đều nhất quán:

---
slug: /category/topic-name
title: Topic Title
sidebar_label: Short Name
description: Short SEO description
---

# Topic Title

## Definition

Giải thích ngắn gọn về chủ đề này là gì và tại sao nó quan trọng.

## Core Concepts

### Concept 1

Giải thích kèm code example khi phù hợp.

### Concept 2

Giải thích kèm code example khi phù hợp.

## Code Examples

```csharp
// Code example thực tế, có thể chạy được
```

## When to Use

Hướng dẫn khi nào nên sử dụng concept/tool/approach này.

## Common Pitfalls

Những lỗi mà lập trình viên thường gặp và cách tránh.

## Key Takeaways

- Tóm tắt điểm 1
- Tóm tắt điểm 2
- Tóm tắt điểm 3

## Interview Questions

**Q: Câu hỏi phỏng vấn mẫu?**
Câu trả lời ngắn gọn, chính xác.

**Q: Một câu hỏi khác?**
Một câu trả lời ngắn gọn khác.

## References

- [Tiêu đề tài liệu tham khảo](https://example.com)
Thứ tự section quan trọng

Giữ các section theo thứ tự như trên. Không phải section nào cũng bắt buộc cho mọi chủ đề, nhưng thứ tự phải nhất quán.

4. Đăng ký vào sidebar​

Mở sidebars.ts và thêm file path (tương đối so với docs/, không có extension) vào mảng items của category đúng:

// Example: adding a new topic under Architecture
items: [
  'architecture/solid-principles',
  'architecture/design-patterns',
  'architecture/your-new-topic',  // <-- thêm ở đây
],

5. Xem trước và xác minh​

# Nếu dev server đang chạy, nó sẽ tự động hot-reload.
# Nếu không:
npm start

Kiểm tra:

  • Trang mới xuất hiện trong sidebar
  • Frontmatter hiển thị đúng (title, description)
  • Tất cả code blocks được highlight đúng
  • Mermaid diagrams hiển thị đúng (nếu có)
  • Links và references hoạt động

6. Commit và gửi​

git add docs/category/your-topic.md sidebars.ts
git commit -m "docs: add topic name to category"
git push

Sau đó mở Pull Request trên GitHub.

Writing Guidelines (Hướng dẫn viết)​

Code Examples (Ví dụ mã)​

  • Sử dụng code có thể chạy được — tránh pseudocode hoặc snippet không compile được.
  • Sử dụng đúng language tag trong fences: ```csharp, ```sql, ```bash.
  • Giữ example tập trung — một concept cho mỗi code block.
  • Thêm inline comment để giải thích phần không rõ ràng.

Ngôn ngữ syntax highlighting được hỗ trợ: bash, csharp, javascript, typescript, python, java, go, rust, sql.

Diagrams (Sơ đồ)​

Sử dụng Mermaid cho sơ đồ:

Các loại diagram được hỗ trợ: flowchart, sequenceDiagram, classDiagram, graph.

Callouts (Lời nhắc)​

Sử dụng Docusaurus admonitions để làm nổi bật thông tin quan trọng:

:::tip[Pro Tip]
Something useful that goes beyond the basics.
:::

:::warning[Watch Out]
A common mistake or edge case to be aware of.
:::

:::danger[Critical]
Something that can cause data loss, security issues, or production failures.
:::

Interview Questions (Câu hỏi phỏng vấn)​

  • Mục tiêu 3-5 câu hỏi cho mỗi chủ đề.
  • Kết hợp cả câu hỏi conceptual (khái niệm) và practical (thực hành).
  • Giữ câu trả lời ngắn gọn nhưng đầy đủ.
  • Đánh dấu câu hỏi nâng cao với (Advanced) trong phần câu hỏi.

Content Quality Checklist (Danh sách kiểm tra chất lượng)​

Trước khi gửi, xác minh nội dung của bạn:

  • Frontmatter đầy đủ (slug, title, sidebar_label, description)
  • Slug duy nhất và sử dụng kebab-case
  • File đã được đăng ký trong sidebars.ts
  • Code examples đúng và có thể chạy được
  • Code fences sử dụng đúng language tag
  • Mermaid diagrams hiển thị đúng (nếu có)
  • Nội dung tuân theo standard section template
  • Interview questions có câu trả lời chính xác
  • Không có lỗi chính tả hoặc ngữ pháp
  • Tất cả links và references hợp lệ

File Naming Convention (Quy tắc đặt tên file)​

Sử dụng kebab-case cho tên file:

solid-principles.md     # đúng
SolidPrinciples.md      # sai
solid_principles.md     # sai

Commit Message Format (Định dạng commit message)​

Sử dụng conventional commit prefix:

docs: add dependency injection to .NET Platform
docs: update SOLID principles with new examples
fix: correct async/await code example
feat: add new category "Cloud & Infrastructure"

Need Help? (Cần trợ giúp?)​

  • Mở issue trên GitHub cho câu hỏi hoặc đề xuất.
  • Xem các chủ đề hiện có trong repository để tham khảo về style và độ sâu.
  • Kiểm tra Docusaurus Docs cho các câu hỏi về nền tảng.