Cách viết tài liệu kỹ thuật mà đồng nghiệp thực sự muốn đọc
Tài liệu kỹ thuật là một trong những phần bị xem nhẹ nhất nhưng lại có ảnh hưởng lớn nhất đến hiệu quả của một đội phát triển. Lập trình viên thường thích viết code hơn viết chữ, nên tài liệu hoặc bị bỏ qua hoặc được viết qua loa cho có. Hậu quả là kiến thức bị nhốt trong đầu vài người, người mới mất nhiều tuần để bắt nhịp, và những câu hỏi giống nhau được hỏi đi hỏi lại. Tài liệu tốt không phải gánh nặng mà là khoản đầu tư nhân lên sức mạnh của cả đội.
Xác định bạn đang viết cho ai
Sai lầm phổ biến nhất khi viết tài liệu là không xác định rõ đối tượng đọc. Một tài liệu cố gắng phục vụ tất cả mọi người thường chẳng phục vụ tốt ai cả. Người mới gia nhập cần một cái nhìn tổng quan và hướng dẫn từng bước để bắt đầu. Một lập trình viên dày dạn đang gỡ lỗi lúc nửa đêm cần thông tin tham khảo chính xác và nhanh chóng. Một người quản lý cần hiểu hệ thống làm gì ở mức cao mà không cần đi vào chi tiết kỹ thuật.
Trước khi viết, hãy tự hỏi người đọc đã biết gì và họ đang cố làm gì khi tìm đến tài liệu này. Câu trả lời sẽ định hình giọng văn, độ sâu và cấu trúc. Một hướng dẫn bắt đầu nhanh khác hoàn toàn với một tài liệu tham khảo đầy đủ, và cố gắng nhồi cả hai vào một chỗ chỉ làm cả hai trở nên kém hiệu quả.
Các loại tài liệu phục vụ mục đích khác nhau
Hiểu rằng có nhiều loại tài liệu với vai trò riêng sẽ giúp bạn viết đúng thứ cần thiết. Mỗi loại trả lời một câu hỏi khác nhau của người đọc.
- Hướng dẫn học tập dẫn dắt người mới qua một ví dụ hoàn chỉnh để họ có trải nghiệm thành công đầu tiên.
- Hướng dẫn thực hành giúp người đã có kiến thức giải quyết một vấn đề cụ thể theo các bước rõ ràng.
- Tài liệu tham khảo mô tả chính xác và đầy đủ từng thành phần, dành cho việc tra cứu nhanh.
- Tài liệu giải thích trình bày bối cảnh và lý do đằng sau các quyết định thiết kế, giúp người đọc hiểu sâu hơn.
Khi bạn trộn lẫn các loại này, người đọc bị bối rối vì không biết nên kỳ vọng điều gì. Tách bạch chúng giúp mỗi tài liệu làm tốt đúng một việc và dễ bảo trì hơn.
Viết để được quét nhanh, không phải đọc tuần tự
Người đọc tài liệu kỹ thuật hiếm khi đọc từ đầu đến cuối; họ quét để tìm đúng phần mình cần. Vì vậy hãy cấu trúc nội dung để hỗ trợ cách đọc này. Dùng tiêu đề rõ ràng và mô tả đúng nội dung bên dưới để người đọc nhảy thẳng đến phần liên quan. Đặt thông tin quan trọng nhất lên đầu thay vì giấu nó ở cuối một đoạn dài. Chia nhỏ những khối văn bản đồ sộ thành các đoạn ngắn và danh sách dễ tiếp thu.
Ví dụ là linh hồn của tài liệu kỹ thuật tốt. Một đoạn mã thực tế mà người đọc có thể sao chép, chạy thử và điều chỉnh đáng giá hơn rất nhiều so với những mô tả trừu tượng dài dòng. Hãy đảm bảo ví dụ đầy đủ và thực sự chạy được, vì một ví dụ sai còn tệ hơn không có ví dụ nào, nó làm xói mòn niềm tin của người đọc vào toàn bộ tài liệu.
Giữ tài liệu sống cùng dự án
Vấn đề lớn nhất của tài liệu không phải là viết nó mà là giữ nó cập nhật. Một tài liệu sai lệch còn nguy hiểm hơn không có tài liệu, vì nó dẫn người đọc đi sai đường một cách tự tin. Cách hiệu quả để chống lại sự lỗi thời là đặt tài liệu càng gần code càng tốt, lý tưởng là trong cùng kho mã, để khi thay đổi code lập trình viên nhớ cập nhật cả tài liệu trong cùng một lần thay đổi.
Một nguyên tắc hữu ích nữa là viết tài liệu vào lúc kiến thức còn tươi mới, ngay sau khi hoàn thành một phần, thay vì để dành làm sau khi mọi chi tiết đã phai nhạt. Hãy coi việc viết tài liệu là một phần của định nghĩa hoàn thành công việc, không phải việc tùy chọn. Cuối cùng, hãy nhớ rằng người hưởng lợi nhiều nhất từ tài liệu tốt thường chính là bạn của sáu tháng sau, khi bạn quay lại một đoạn code mình từng viết và không còn nhớ mình đã nghĩ gì lúc đó. Viết tài liệu là một hành động tử tế với chính mình và với cả đội trong tương lai.
