Tài liệu được đọc khi nó ngắn, đúng, nằm ở chỗ người ta sẽ tìm, và trả lời đúng câu hỏi mà người đọc đang có. Hãy viết cho một người cụ thể trong một tình huống cụ thể, bắt đầu từ cách chạy dự án và những quyết định quan trọng, và cập nhật tài liệu ngay trong cùng lần thay đổi với mã.
Chào bạn, đây là Nhà Lập Trình. Lập trình viên nổi tiếng là ghét viết tài liệu, và cũng ghét đọc tài liệu, nhất là tài liệu dài và sai. Nhưng ai cũng từng ước có tài liệu khi nhận một dự án lạ. Tập này kể cách viết thứ tài liệu mà chính bạn sẽ muốn đọc.
Vì sao tài liệu không ai đọc?
Hầu hết tài liệu không được đọc vì một trong ba lý do. Thứ nhất, nó quá dài. Người đọc cần biết một điều, và phải lội qua hai mươi trang mới tìm thấy, hoặc không tìm thấy.
Thứ hai, nó sai. Tài liệu viết hai năm trước, hệ thống đã đổi nhiều lần. Người đọc làm theo, gặp lỗi, và từ đó không bao giờ tin tài liệu nữa. Một lần sai đủ làm mất niềm tin vào cả bộ tài liệu.
Thứ ba, nó nằm ở chỗ không ai tìm. Một thư mục chung trên ổ mạng mà người mới không biết, một trang trong hệ thống quản lý nội dung mà không ai nhớ đường dẫn.
Viết tài liệu tốt là tránh cả ba: ngắn, đúng, dễ tìm. Không cần nhiều, cần đúng chỗ.
Viết cho ai, trong tình huống nào
Trước khi viết, hãy hình dung một người đọc cụ thể. Một lập trình viên mới vào đội, ngày đầu tiên, cần chạy được dự án trên máy mình. Một đồng nghiệp đang trực lúc nửa đêm, hệ thống báo lỗi, cần biết khởi động lại dịch vụ thế nào. Một người sáu tháng sau, tự hỏi vì sao đội chọn cách lưu trữ này.
Mỗi người đọc cần một loại tài liệu khác nhau. Người mới cần hướng dẫn từng bước. Người trực đêm cần danh sách thao tác ngắn, rõ, không cần giải thích dài. Người sáu tháng sau cần lý do.
Khi bạn trộn lẫn tất cả vào một tài liệu, không ai được phục vụ tốt. Người trực đêm phải đọc qua ba trang lịch sử thiết kế mới tới được lệnh khởi động lại.
Một mẹo đơn giản: đặt tiêu đề tài liệu theo câu hỏi người đọc có. Không phải hệ thống thanh toán, mà là khi thanh toán bị lỗi thì làm gì. Người đọc tìm thấy ngay thứ họ cần.
Ba loại tài liệu đáng viết nhất
Nếu chỉ có thời gian viết ba thứ, mình sẽ chọn những thứ này. Thứ nhất là hướng dẫn chạy dự án: cài những gì, cấu hình thế nào, chạy lệnh gì, làm sao biết đã chạy đúng. Đặt ngay trong thư mục gốc của dự án. Kiểm tra nó bằng cách nhờ người mới làm theo, chỗ nào họ bí là chỗ cần sửa.
Thứ hai là sổ tay xử lý sự cố: những sự cố hay gặp, dấu hiệu nhận biết, các bước xử lý. Viết ngắn gọn, từng bước, như danh sách kiểm tra. Mỗi lần có sự cố mới được xử lý, bổ sung vào.
Thứ ba là nhật ký quyết định: mỗi quyết định kỹ thuật quan trọng một trang ngắn, ghi bối cảnh lúc đó, các lựa chọn đã cân nhắc, lựa chọn cuối cùng và lý do. Vì sao dùng cơ sở dữ liệu này, vì sao tách dịch vụ này ra riêng.
Loại thứ ba thường bị bỏ qua nhất, nhưng lại quý nhất về lâu dài. Mã cho biết hệ thống làm gì. Chỉ nhật ký quyết định cho biết vì sao, và cho người sau biết điều kiện nào thay đổi thì nên xem lại quyết định.
Đặt tài liệu cạnh mã, sửa cùng lúc với mã
Cách tốt nhất để tài liệu không bị bỏ quên là đặt nó cạnh mã, trong cùng kho mã. Khi ai đó sửa mã, tài liệu nằm ngay đó, dễ thấy, dễ sửa theo.
Hãy tập thói quen: thay đổi nào làm tài liệu sai thì sửa tài liệu trong cùng thay đổi đó. Khi xem lại mã cho đồng nghiệp, hỏi thêm: thay đổi này có cần cập nhật tài liệu không.
Tài liệu nằm cạnh mã còn có lợi là có lịch sử thay đổi. Bạn biết ai sửa tài liệu, sửa lúc nào, cùng với thay đổi mã nào.
Với những tài liệu cho người không làm kỹ thuật, như hướng dẫn dùng phần mềm cho nhân viên, có thể đặt ở nơi khác dễ truy cập hơn. Nhưng tài liệu kỹ thuật thì chỗ tốt nhất là cạnh mã.
Viết ngắn, viết thật, viết ngay
Viết câu ngắn, từ đơn giản. Người đọc tài liệu kỹ thuật thường đang vội, đang căng thẳng, hoặc đang đọc bằng ngôn ngữ không phải tiếng mẹ đẻ. Họ cần hiểu ngay lần đọc đầu.
Dùng ví dụ cụ thể thay vì mô tả chung chung. Một lệnh thật, một cấu hình mẫu, một đoạn dữ liệu mẫu. Người đọc sao chép và sửa dễ hơn nhiều so với hiểu một đoạn mô tả.
Ghi ngày cập nhật cuối và người phụ trách. Người đọc biết tài liệu mới hay cũ, và biết hỏi ai khi có gì không rõ.
Và viết ngay khi còn nhớ. Ngay sau khi xử lý xong một sự cố, ngay sau khi quyết định một điều quan trọng, dành mười lăm phút viết lại. Một tuần sau, bạn đã quên một nửa. Một tháng sau, bạn sẽ không viết nữa.
Câu hỏi thường gặp
Đội lập trình nhỏ cần những tài liệu gì?
Tối thiểu là hướng dẫn chạy dự án, sổ tay xử lý sự cố thường gặp và nhật ký các quyết định kỹ thuật quan trọng kèm lý do. Ba thứ này giải quyết phần lớn câu hỏi của người mới và người trực sự cố.
Làm sao để tài liệu không bị lỗi thời?
Đặt tài liệu cạnh mã trong cùng kho, sửa tài liệu trong cùng thay đổi với mã, và nhắc nhau trong lúc xem lại mã. Ghi ngày cập nhật cuối để người đọc biết mức độ tin cậy.
Nhật ký quyết định kỹ thuật là gì?
Là các ghi chép ngắn cho từng quyết định quan trọng, gồm bối cảnh, các lựa chọn đã cân nhắc, lựa chọn cuối cùng và lý do. Nó giúp người sau hiểu vì sao hệ thống được thiết kế như vậy.
Tài liệu kỹ thuật nên dài bao nhiêu?
Càng ngắn càng tốt miễn đủ để người đọc làm được việc họ cần. Tách thành nhiều tài liệu nhỏ theo tình huống thay vì một tài liệu dài chứa mọi thứ.
Làm sao kiểm tra tài liệu hướng dẫn có tốt không?
Nhờ một người mới làm theo từ đầu mà không hỏi ai. Chỗ nào họ bí hoặc làm sai là chỗ tài liệu cần sửa.
