Technical Documentation (tài liệu kỹ thuật), mà nhiều anh em Dev thường gọi là Docs, là "bộ mặt" của mọi hệ thống phần mềm.
Nó giúp developer (đặc biệt là những anh em mới vào dự án) hiểu logic, vận hành code, và nhanh chóng bắt nhịp được với dự án mới.
Tuy nhiên, nhiều dự án mắc sai lầm khi cố viết documentation càng dài, càng chi tiết và nghĩ như vậy là càng tốt, dẫn đến phản tác dụng.
Bài viết này sẽ phân tích 4 lý do tại sao documentation nên ngắn gọn, súc tích.
1. Quá tải thông tin - Não người không phải là cái máy
Theo nghiên cứu tâm lý học nhận thức của George Miller vào năm 1956, não người trung bình chỉ có thể giữ và xử lý được 7 ± 2 đơn vị thông tin (tức là từ 5 đến 9 đơn vị thông tin) cùng lúc.
Một documentation dài dòng với hàng trăm trang, mô tả chi tiết từng hàm sẽ khiến người đọc "chết đuối" trong biển chữ.
Một ví dụ thực tế có thể nhắc đến đó là các library/framework nổi tiếng như React hay FastAPI đã rất thành công nhờ vào việc documentation của họ tập trung vào code samples thay vì quá nhiều lý thuyết dài dòng.
2. Vấn đề về maintainance - Càng dài, càng dễ lỗi thời (outdated)
Documentation cần được cập nhật song song với code.
Nếu tài liệu quá dài, anh em developer sẽ rất ngại sửa nó, dẫn đến documentation bị outdated, hay nói đơn giản là code một đằng, documentation một nẻo – cái này còn gây ra vấn đề lớn hơn cả việc không có documentation.
3. Khiến lập trình viên mới join dự án "lạc lối"
Documentation dài rất dễ khiến anh em Dev mới vào dự án hoang mang, nhất là những anh em mới ra trường ít kinh nghiệm.
Thay vì hướng dẫn "Hello world" trong 5 phút, họ phải đọc 20 trang về kiến trúc hệ thống.
Quy tắc vàng:
-
Phân chia documentation thành những mục lớn giống như một cuốn sách giáo khoa:
- Tổng quan (1 trang): Mục đích, cách cài đặt, ví dụ cơ bản.
- Hướng dẫn chi tiết (khoảng 10 trang): Tutorials, common use cases.
- Tài liệu chuyên sâu: Dành cho expert (API references, design decisions, ...)
-
Bạn cũng có thể tham khảo mô hình Diátaxis của Daniele Procida. Xác định 4 nhu cầu riêng biệt và phân loại thành 4 hình thức documentation tương ứng là: tutorials, how-to guides, explanation và reference.
4. Thời gian là vàng là bạc
Anh em nào từng tham gia viết documentation thì cũng hiểu việc này tốn rất nhiều thời gian.
Vậy nên, để tối ưu thời gian thì bạn nên đầu tư vào:
- Viết code tự mô tả (self-documenting code): Đặt tên biến, tên hàm rõ ràng và đúng mục đích. Ví dụ đặt tên hàm để tính toán doanh thu thì nên viết đầy đủ ra là
calculateRevenue(), thay vìcalcRev()). - Tăng tỉ lệ code coverage cho unit test: Test cases tốt cũng là một dạng documentation.
- Code review: Sự phản biện của một người code reviewer sẽ giúp phân tích đa chiều, và có thể giúp cải thiện logic code dễ hiểu hơn.
Lời khuyên tự kinh nghiệm cá nhân - Làm thế nào để viết documentation hiệu quả:
- Tối giản nhưng đủ ý: Dùng bullet point, code snippet, hình ảnh.
- Tự động hóa: Sử dụng tool như JSDoc, Sphinx, Doxygen để sinh documentation từ code comment.
- Quan sát và hiểu nhu cầu của anh em Dev: Đặt câu hỏi "Họ thực sự cần gì?" thay vì cố gắng giải thích mọi thứ.
- Khuyến khích anh em trong team tích cực góp ý: Ai cũng biết rằng documentation ngắn gọn thì sẽ dễ bổ sung, chỉnh sửa hơn. Thế nhưng nếu không có anh em trong team đọc, nhận xét và phản hồi góp ý thì sẽ rất khó để chúng ta biết được những điểm cần cải tiến.
Kết luận: Documentation chất lượng KHÔNG ĐO BẰNG SỐ TRANG
Documentation dài không phải là documentation tốt.
Hãy coi nó như một tấm bản đồ: Đủ chi tiết để dẫn đường, nhưng không quá rườm rà khiến người dùng lạc lối.
Như giáo sư Peter Drucker đã từng nói: "Không có gì vô ích bằng việc cố làm cho hiệu quả những việc mà đáng ra bạn không cần làm."
Câu hỏi thảo luận:
- Anh em đã từng gặp documentation nào quá dài và gây khó hiểu chưa?
- Làm thế nào để cân bằng giữa ngắn gọn và đầy đủ trong dự án của anh em?
Hãy chia sẻ quan điểm của anh em ở phần bình luận.
LỜI NHẮN
Theo dõi blog của mình để đọc thêm về những câu chuyện thú vị trong ngành CNTT: https://tmsanghoclaptrinh.com/
Facebook CLB Lập trình - THPT Ngọc Tảo: https://www.facebook.com/clb.it.ngoctao/
Youtube Tờ Mờ Sáng học Lập trình: https://www.youtube.com/@tmsanghoclaptrinh
Hẹn gặp lại 👋