Tài liệu kỹ thuật không phải là một tác vụ phụ mà bạn chỉ hoàn thành sau khi mã nguồn đã biên dịch xong. Nó nằm ở trung tâm của mọi dự án phần mềm, quyết định liệu một lập trình viên mới có thể sửa lỗi ngay trong ngày đầu tiên hay liệu người dùng có từ bỏ sản phẩm của bạn sau năm phút bối rối. Tài liệu tốt giúp người dùng hoàn thành các tác vụ thực tế. Chúng giúp những người bảo trì trong tương lai hiểu tại sao một module tồn tại và cách thay đổi nó mà không làm hỏng mọi thứ. Tuy nhiên, quá nhiều đội ngũ coi tài liệu là một việc làm sau cùng, một tệp README được soạn vội vàng, hoặc một trang wiki bị bỏ mặc cho mục nát. Viết tài liệu thực sự hữu ích là một kỹ năng mà bạn có thể cải thiện một cách có chủ đích.
Hiểu rõ độc giả trước khi viết
Trước khi gõ một tiêu đề duy nhất, hãy quyết định xem ai là người đang đọc. Một quản trị viên cơ sở dữ liệu đang tìm kiếm các thiết lập connection pool sẽ không có điểm chung nào với một lập trình viên front-end đang tìm kiếm các React component props. Người dùng cuối cần các bước được đánh số và ảnh chụp màn hình, chứ không phải các sơ đồ kiến trúc. Họ muốn biết cách xuất một tệp PDF, chứ không phải cách rendering pipeline hoạt động. Các lập trình viên khi tích hợp thư viện của bạn cần các function signatures chính xác, mã lỗi và các đoạn mã có thể sao chép và dán. Quản trị viên hệ thống cần các điều kiện tiên quyết để cài đặt, các biến môi trường và các quy trình khắc phục sự cố bắt đầu với các chế độ lỗi phổ biến nhất.
Nếu bạn cố gắng phục vụ cả ba nhóm bằng một khối văn bản khổng lồ, tất cả mọi người đều sẽ thua thiệt. Hãy tạo ra các lộ trình riêng biệt. Ngay cả một trang duy nhất cũng có thể được phân đoạn rõ ràng với các tiêu đề như "Dành cho người vận hành" và "Dành cho lập trình viên client". Mục tiêu là loại bỏ sự ma sát về mặt tư duy khi phải tự hỏi: "Đoạn văn này có dành cho mình không?"
Loại bỏ sự rườm rà
Sự rõ ràng quan trọng hơn sự cầu kỳ. Hãy sử dụng câu ngắn. Hãy sử dụng thể chủ động. "Khởi tạo cơ sở dữ liệu" rõ ràng hơn là "Cơ sở dữ liệu nên được khởi tạo bởi người dùng." Khi bạn phải sử dụng một thuật ngữ kỹ thuật như "idempotency" hoặc "serialization", hãy định nghĩa nó ngay trong dòng hoặc liên kết đến một bảng thuật ngữ. Đừng giả định rằng người đọc đã có kiến thức nền tảng.
Một bài kiểm tra thực tế: hãy thử đọc to đoạn văn của bạn. Nếu bạn bị hụt hơi, câu đó quá dài. Một bài kiểm tra khác: hãy thay thế các động từ cầu kỳ bằng các động từ đơn giản. Nếu một cụm từ như "utilize the API" có thể trở thành "use the API" mà không làm mất đi ý nghĩa, hãy thực hiện thay đổi đó. Ngôn ngữ bình dân không có nghĩa là ngôn ngữ hạ thấp trình độ. Nó có nghĩa là ngôn ngữ chính xác được loại bỏ các từ ngữ đệm rườm rà của doanh nghiệp.
Cấu trúc thực sự hữu ích
Một bản hướng dẫn lộn xộn còn gây lãng phí thời gian hơn là không có bản hướng dẫn nào. Hãy coi tài liệu của bạn như một cái phễu. Ở trên cùng, hãy đặt một phần tổng quan ngắn gọn giải thích dự án làm gì và ai nên quan tâm. Tiếp theo là các hướng dẫn cài đặt mà không giả định bất cứ điều gì về thiết lập cục bộ của người đọc. Sau đó, thêm các bài hướng dẫn (tutorials) dẫn dắt qua các kịch bản thực tế, hoàn chỉnh từ đầu đến cuối. Tiếp đến là các tài liệu tham khảo API. Những tài liệu này nên đầy đủ nhưng có thể quét nhanh được, được nhóm theo tài nguyên hoặc chức năng thay vì liệt kê theo thứ tự bảng chữ cái. Cuối cùng, hãy đặt các hướng dẫn khắc phục sự cố giải quyết các triệu chứng cụ thể. Một người dùng nhận được thông báo "Connection refused" sẽ cần một câu trả lời khác với người thấy "Permission denied". Hãy nhóm các lỗi theo thông báo hoặc theo ngữ cảnh, thay vì theo các danh mục trừu tượng.
Danh sách và các khối mã (code blocks) giúp ngắt các đoạn văn dày đặc và cho phép người đọc quét nhanh để tìm chính xác lệnh họ cần. Một danh sách dấu đầu dòng được đặt đúng chỗ có thể biến một đoạn văn gây bối rối thành một chuỗi các hành động.
Hãy trình diễn, đừng chỉ nói suông
Những giải thích trừu tượng sẽ làm người dùng nản lòng. Nếu bạn mô tả cách cấu hình một công cụ, hãy hiển thị chính xác nội dung tệp. Cung cấp các đoạn mã mẫu để cài đặt, để khởi tạo và cho các cấu hình phổ biến. Hiển thị các đầu vào mẫu và đầu ra mong đợi cạnh nhau. Nếu API của bạn trả về JSON, hãy hiển thị JSON đó. Nếu một công cụ CLI tạo ra đầu ra dạng bảng, hãy hiển thị bảng đó. Đừng bao giờ tin rằng một mô tả về quy trình làm việc là tương đương với một bản trình diễn.
Quan trọng nhất là hãy kiểm tra mọi ví dụ trong một môi trường sạch trước khi bạn xuất bản. Hãy sao chép đoạn mã của chính bạn vào một container hoặc máy ảo mới. Nếu nó thất bại vì bạn quên đề cập đến một dependency, bạn đã tự cứu mình khỏi một cơn mưa các vấn đề phát sinh. Các ví dụ cụ thể mang lại lợi nhuận trên vốn đầu tư (ROI) lớn nhất trong viết lách kỹ thuật vì chúng biến sự không chắc chắn thành hành động.
Hãy giữ cho nó luôn sống động
Tài liệu bị lỗi thời nhanh hơn cả mã nguồn. Một method signature thay đổi, một cổng mặc định bị chuyển, một dependency bị thay thế, và đột nhiên các hướng dẫn của bạn dẫn đến một ngõ cụt.