Tạo tài liệu và chia sẻ kiến ​​thức code với AI

Tài liệu chẳng ai viết

Trong bài học trước, chúng ta đã tìm hiểu về đánh giá và tái cấu trúc code. Giờ hãy xây dựng trên nền tảng đó. Hãy hỏi bất kỳ nhóm phát triển nào: "Tài liệu của các bạn có được cập nhật không?" Chắc chắn họ sẽ cười.

Tài liệu giống như bông cải xanh trong phát triển phần mềm - ai cũng biết nó tốt cho họ, nhưng chẳng ai muốn ăn nó. Code được phát hành, tính năng được ra mắt, tài liệu... được thêm vào danh sách công việc của sprint tiếp theo. Rồi lại chuyển sang sprint sau đó. Cuối cùng thì được đánh dấu là "sẽ không sửa".

Trí tuệ nhân tạo (AI) thay đổi phương trình này một cách cơ bản. Không phải vì nó làm cho việc viết tài liệu trở nên thú vị, mà vì nó làm cho việc này gần như không cần nỗ lực. Việc từng mất cả buổi chiều giờ chỉ mất 15 phút.

5 loại tài liệu phát triển phần mềm

Mỗi loại yêu cầu một phương pháp AI khác nhau:

Hãy cùng xem xét từng bước một.

Tài liệu API từ code

Đây là lúc tài liệu AI thực sự tỏa sáng. Quy trình như sau:

Bước 1: Cung cấp code endpoint

📍 Nơi dán: Mở ChatGPT (chat.openai.com), Claude (claude.ai) hoặc Gemini (gemini.google.com) và bắt đầu một cuộc trò chuyện mới.

📋 Cách sao chép prompt này: Nhấp vào bất kỳ đâu bên trong khối màu xám, nhấn Cmd+A rồi Cmd+C (Mac) hoặc Ctrl+A rồi Ctrl+C (Windows). Hoặc sử dụng biểu tượng sao chép xuất hiện.

Tạo tài liệu API cho endpoint này.
Bao gồm: mô tả, tham số, ví dụ yêu cầu/phản hồi
code lỗi và yêu cầu xác thực.

Framework: Express.js với TypeScript
Xác thực: Bearer token (JWT)

[dán code endpoint]
[dán loại yêu cầu/phản hồi]

✏️ ​​Cách điền thông tin chi tiết của bạn: Thay thế mỗi [] và trình giữ chỗ trong ngoặc bằng thông tin cụ thể từ tình huống thực tế của bạn. Thông tin đầu vào mơ hồ sẽ tạo ra kết quả mơ hồ — hãy cụ thể.

👀 Những gì bạn sẽ thấy: Trong vòng vài giây, AI sẽ trả về một phản hồi có cấu trúc dựa vào prompt ở trên. Hãy đọc kỹ và coi đó là bản nháp, không phải câu trả lời cuối cùng.

📌 Nên làm gì với kết quả: Lưu phản hồi vào file Notes. Chọn đề xuất có hiệu quả cao nhất và thực hiện nó trong tuần này — đừng thử mọi thứ cùng một lúc.

⚠️ Nếu kết quả không ổn: Nếu các đề xuất có vẻ chung chung, hãy dán nội dung này: "Hãy cụ thể hơn với ngữ cảnh thực tế của tôi. Bỏ qua lời khuyên chung chung." Nếu nó bỏ qua các chi tiết quan trọng bạn đã cung cấp, hãy hỏi: "Bạn đã bỏ sót [X] trong ngữ cảnh của tôi — hãy thực hiện lại với điều đó làm ràng buộc chính."

Bước 2: AI tạo ra các tài liệu có cấu trúc

Đối với một endpoint như:

router.post('/api/projects/:projectId/tasks',
  authMiddleware,
  validate(CreateTaskSchema),
  TaskController.create
);

AI tạo ra:

## Create Task

Creates a new task within a project.

**Endpoint:** `POST /api/projects/:projectId/tasks`
**Authentication:** Required (Bearer token)

### Parameters

| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| projectId | string (UUID) | path | yes | The project to add the task to |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | yes | Task title (1-200 chars) |
| description | string | no | Detailed description |
| assignee_id | string (UUID) | no | User to assign |
| priority | enum | no | low, medium, high, urgent |
| due_date | string (ISO 8601) | no | Task deadline |

### Example Request

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Implement search feature",
  "priority": "high",
  "assignee_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

### Success Response (201)

{
  "id": "task_abc123",
  "title": "Implement search feature",
  "status": "open",
  "priority": "high",
  "created_at": "2026-02-05T10:30:00Z"
}

### Error Responses

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Invalid request body |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Not a project member |
| 404 | PROJECT_NOT_FOUND | Project doesn't exist |

Việc này chỉ mất khoảng 10 giây để AI thực hiện. Viết thủ công sẽ mất 15-20 phút cho mỗi endpoint. Với một API có 30 endpoint, bạn sẽ tiết kiệm được cả một ngày làm việc.

Giải thích code cũ

Được thừa hưởng một codebase không có tài liệu? Đây là lúc AI tỏa sáng.

Hãy giải thích chức năng của đoạn code này bằng ngôn ngữ dễ hiểu. Sau đó, tạo
một chú thích tài liệu cho nó. Đối tượng là một lập trình viên trung cấp
đang gia nhập nhóm của chúng ta.

[dán hàm cũ phức tạp]

Đối với một hàm phức tạp, AI sẽ tạo ra một cái gì đó như sau:

def reconcile_ledger(entries, cutoff_date, account_map):
    """
    Đối chiếu các mục nhập sổ cái tài chính với account map.

    Hàm này xử lý các mục nhập sổ cái thô và:
    1. Lọc các mục nhập đến ngày giới hạn
    2. Nhóm các mục nhập theo code tài khoản
    3. Xác thực từng nhóm so với cấu trúc tài khoản dự kiến
      trong account_map
    4. Xác định sự khác biệt (các mục nhập bị thiếu, 
       số dư không khớp, giao dịch trùng lặp)
    5. Trả về báo cáo đối chiếu

    Tham số:
        entries: Danh sách các đối tượng LedgerEntry từ cơ sở dữ liệu
        cutoff_date: Chỉ xử lý các mục nhập vào hoặc trước ngày này
        account_map: Từ điển ánh xạ code tài khoản với số dư dự kiến
                     và các quy tắc xác thực

    Trả về:
        ReconciliationReport with:
        - matched: các mục nhập được đối chiếu chính xác
        - discrepancies: các mục nhập có vấn đề
        - missing: các mục nhập dự kiến ​​không được tìm thấy
        - summary: kết quả đối chiếu tổng thể trạng thái

    Lưu ý: Vòng lặp lồng nhau ở dòng 47 là có chủ ý — nó xử lý
    các giao dịch được chia nhỏ trong đó một mục nhập sổ cái duy nhất tương ứng với
    nhiều code tài khoản.
    """

Ghi chú cuối cùng đó rất quan trọng. AI có thể giải thích tại sao code trông bất thường, điều này thường có giá trị hơn việc giải thích chức năng của nó.

Test nhanh: Kiểm tra sơ bộ tài liệu

Đọc bình luận tài liệu do AI tạo ra này. Điều gì đáng ngờ?

def get_users(status="active", limit=100):
    """
    Retrieves users filtered by status.

    Args:
        status: Filter by user status (active, inactive, pending)
        limit: Maximum number of users to return (default 100)

    Returns:
        List of User objects matching the criteria

    Raises:
        DatabaseError: If the database connection fails
    """

Điểm đáng ngờ: Liệu hàm này có thực sự gây ra lỗi DatabaseError không? Hay AI giả định điều đó vì các hàm cơ sở dữ liệu thường có thể gây ra lỗi này? Luôn luôn xác minh rằng những hành vi được ghi lại khớp với hành vi thực tế của code. AI đôi khi ghi lại những gì code nên làm chứ không phải những gì nó thực sự làm.

Tạo README

Đối với các dự án hoặc kho lưu trữ mới chưa từng có README đúng cách:

Tạo README.md cho dự án này dựa trên cấu trúc của nó.

Đây là cấu trúc thư mục:
[dán kết quả của lệnh tree]

Đây là package.json (hoặc requirements.txt, go.mod, v.v.):
[dán file dependency]

Đây là file cấu hình chính:
[dán cấu hình]

Bao gồm: mô tả dự án, điều kiện tiên quyết, hướng dẫn thiết lập,
chạy cục bộ, chạy thử nghiệm, triển khai và tổng quan cấu trúc dự án.

AI tạo ra một README toàn diện mà các thành viên nhóm mới có thể thực sự làm theo. Điều quan trọng là cung cấp các file dự án thực sự — AI sẽ trích xuất những lệnh thiết lập, dependency và cấu hình chính xác từ các file thực tế thay vì đoán mò.

Tài liệu kiến ​​trúc

Điều này đòi hỏi một cách tiếp cận hợp tác. Trí tuệ nhân tạo (AI) không thể hiểu kiến ​​trúc hệ thống của bạn chỉ từ code - nó cần sự hướng dẫn của bạn về "lý do".

Hãy giúp tôi lập tài liệu kiến ​​trúc hệ thống. Tôi sẽ mô tả
thiết kế cấp cao và bạn sẽ tạo tài liệu có cấu trúc.

Hệ thống: Xử lý đơn hàng thương mại điện tử
Các thành phần:
- Cổng API (Express.js) - xử lý xác thực, giới hạn tốc độ
- Dịch vụ Đơn hàng (Python) - logic nghiệp vụ, xác thực
- Dịch vụ Thanh toán (Go) - tích hợp Stripe
- Dịch vụ Thông báo (Node.js) - email, SMS, thông báo đẩy
- PostgreSQL - đơn hàng, người dùng
- Redis - cache phiên, giới hạn tốc độ
- RabbitMQ - giao tiếp bất đồng bộ giữa các dịch vụ

Tạo tài liệu kiến ​​trúc bao gồm:
1. Mô tả sơ đồ tổng quan hệ thống
2. Trách nhiệm của các thành phần
3. Mô hình giao tiếp
4. Luồng dữ liệu cho một đơn hàng điển hình
5. Các chế độ lỗi và cách xử lý chúng

AI tạo cấu trúc và văn bản. Bạn xác minh tính chính xác và thêm ngữ cảnh mà chỉ con người mới biết - tại sao một số quyết định được đưa ra, những sự đánh đổi nào đã được xem xét, kế hoạch tương lai là gì.

Cập nhật tài liệu thường xuyên

Phần khó nhất của việc lập tài liệu không phải là tạo ra nó—mà là giữ cho nó luôn cập nhật. Dưới đây là các chiến lược được hỗ trợ bởi AI:

Kiểm tra tài liệu PR:

Đây là bản so sánh PR. Liệu nó có thay đổi bất kỳ hành vi nào cần được
phản ánh trong tài liệu API của chúng ta không?

[dán bản so sánh]
[dán tài liệu hiện tại cho các endpoint bị ảnh hưởng]

Tạo nhật ký thay đổi:

Tạo một mục nhật ký thay đổi từ các commit này.
Viết nó từ góc nhìn của người dùng - những gì đã thay đổi
đối với họ, chứ không phải các chi tiết triển khai nội bộ.

[dán đầu ra git log]

Cập nhật tài liệu hướng dẫn người mới:

Đây là hướng dẫn người mới hiện tại của chúng tôi và danh sách
các thay đổi chúng tôi đã thực hiện đối với môi trường phát triển
trong quý vừa qua. Những phần nào cần được cập nhật?

[Dán hướng dẫn giới thiệu]
[Dán danh sách thay đổi môi trường]

Bài tập thực hành: Viết tài liệu cho code thực tế

Chọn một trong những bài tập này (hoặc làm cả ba):

1. Tài liệu API: Lấy một endpoint từ dự án của bạn và tạo tài liệu API hoàn chỉnh bằng AI. So sánh nó với bất kỳ tài liệu hiện có nào.
2. Giải thích code cũ: Tìm hàm gây khó hiểu nhất trong codebase của bạn. Hãy để AI giải thích nó và tạo chú thích tài liệu.
3. Kiểm tra README: Hãy để AI xem xét README của dự án so với cấu trúc dự án thực tế. Hỏi nó xem điều gì còn thiếu hoặc đã lỗi thời.

Mỗi bài tập sẽ mất 5-10 phút và giúp bạn tiết kiệm hàng giờ làm việc viết tài liệu trong tương lai.

Những điểm chính cần ghi nhớ

• AI giúp việc lập tài liệu trở nên dễ dàng hơn rất nhiều - chỉ mất 15 phút thay vì cả buổi chiều
• Cung cấp code thực tế để có tài liệu API chính xác, chứ không phải chỉ mô tả code
• Kiểm tra tài liệu do AI tạo ra so với hành vi thực tế - AI đôi khi lập tài liệu về hành vi lý tưởng
• Sử dụng AI để giải thích code cũ cho quá trình làm quen và chuyển giao kiến ​​thức
• Tích hợp việc lập tài liệu vào quy trình làm việc của PR để tài liệu luôn được cập nhật
• Tài liệu kiến ​​trúc yêu cầu sự hợp tác - AI xây dựng cấu trúc, bạn kiểm chứng