Hướng dẫn Viết Tài liệu cho Dự án

Bài viết này hướng dẫn phương pháp tổ chức và quản lý thư mục tài liệu dành cho một dự án cụ thể bên trong PARA Workspace. Để tham khảo sâu thuật toán của AI Agent, vui lòng xem Chi tiết Workflow /docs.

Nguyên tắc Thiết kế: Internal-First

Tài liệu là linh hồn của tính liên tục. Trong PARA, tài liệu được lưu trữ theo kiến trúc Dual-Pathing (hai luồng) dựa trên nguyên tắc Internal-First.

Nguyên tắc Internal-First (Ưu tiên Nội bộ) quy định: Tất cả các tài liệu phải được soạn thảo và kiểm duyệt ở không gian làm việc an toàn nội bộ trước khi xuất bản ra thế giới bên ngoài hoặc gắn vào mã nguồn.

Phân biệt Hai vị trí Lưu trữ

Cấu trúc dự án điển hình như sau:

Projects/my-awesome-app/
├── docs/               ← (1) WORKSPACE INTERNAL DOCS: Luôn nháp tại đây
│   ├── README.md         ← Doc Index
│   └── architecture.md
│
└── repo/               ← THƯ MỤC CHỨA SOURCE CODE
    └── docs/           ← (2) SOURCE CODE DOCS: Chỉ chứa file đã Publish
        └── architecture.md

1. Thư mục `docs/` (Nội bộ)

Nằm ở cấp cao nhất của thư mục dự án, ngay bên ngoài thư mục được git theo dõi (repo/).

Mục đích: Là bản nháp đang hoàn thiện, chứa các thảo luận nội bộ, bản vẽ thô, hay notes dành riêng cho bạn và AI Agent.
Tính riêng tư: An toàn tuyệt đối. Git sẽ không bao giờ theo dõi thư mục này. Nó chỉ tồn tại trên máy của bạn và trong bộ nhớ của AI.
Luồng công việc: Khi bạn bảo AI “Hãy viết docs cho tính năng X”, AI sẽ tự động tạo file trong thư mục này. Bạn có thể tự do viết nháp bằng tiếng Việt (hoặc ngôn ngữ mẹ đẻ), chèn các liên kết đến các file artifacts/ hay sessions/ nội bộ.

2. Thư mục `repo/docs/` (Public)

Nằm bên trong thư mục thực thụ chứa source code (repo/).

Mục đích: Là tài liệu chính thức gửi đến người dùng cuối, đồng nghiệp rview code, hoặc public ra cộng đồng mã nguồn mở.
Tính riêng tư: Công khai. Mọi file ở đây sẽ được commit và push lên GitHub/GitLab.
Luồng công việc: Chỉ được sinh ra sau quá trình Publisher. Tài liệu tại đây có thể đã được AI dịch thuật sang tiếng Anh từ bản nháp tiếng Việt ở thư mục docs/, đồng thời các URL tham chiếu cục bộ rác đã bị gỡ bỏ.

Cách Khởi tạo Tài liệu Nhanh

Đừng tạo thủ công, hãy sử dụng quy trình tư duy của PARA Agent!

Mỗi khi bạn vừa clone một project mới về, hoặc tạo xong mã nguồn cơ bản, hãy yêu cầu AI khởi tạo tài liệu với lệnh:

/docs new my-awesome-app

(Xem danh sách đầy đủ tham số tại bài: Workflow /docs).

Điều gì sẽ xảy ra?

Thay vì tạo hàng loạt file template sáo rỗng, Agent sẽ:

Đọc lướt qua các file mã nguồn hiện có.
Xác định xem đây là dự án Web App, CLI Script, hay Library.
Chẩn đoán và chỉ tạo ra các file Markdown cần thiết.
Khởi tạo một file Danh mục chính: docs/README.md.

File Index Bắt buộc (`docs/README.md`)

Bạn sẽ chú ý AI luôn ép tạo ra file docs/README.md. Đây là Doc Index của dự án. File này đóng vai trò như một Master Table, liệt kê tất cả các file docs đang có và ngày cập nhật cuối cùng.

Tại sao lại cần nó? Nó giúp tiết kiệm hàng ngàn Token cho hệ thống AI của bạn. Mỗi khi bạn /open bắt đầu ngày mới, hoặc yêu cầu AI tra cứu tài liệu, AI chỉ cần nhắm mắt đọc file docs/README.md là 10 dòng này để biết vị trí của mọi kiến trúc hệ thống, thay vì phải chạy các lệnh ls đệ quy toàn bộ thư mục một cách mù quáng.

Từ Nháp đến Xuất bản

Quy trình phát triển tài liệu thực tế của một Developer trong PARA:

Nháp: Gọi /docs new. Chỉnh sửa thoải mái file ở docs/architecture.md. Nhờ AI nhận xét.
Review: Khi code đã hòm hòm, sử dụng lệnh /docs review để AI quét sự mất đồng bộ giữa Code (chạy thực tế) và Docs (bị lạc hậu).
Publish: Lúc chuẩn bị Push Code, chạy lệnh /docs publish. AI sẽ sao chép tóm lược nội dung từ thư mục nội bộ vào trong repo/docs/ (tự động dịch sang tiếng cờ nếu project yêu cầu).
Release: Commit và hoàn thành chu kỳ.

→ Lớp tiếp theo: Hướng dẫn Lập kế hoạch & Backlog