# Đọc Docs for Developers như một FDE: viết để đội khách bớt phải gọi bạn

> Ví dụ xuyên suốt của sách là một API dịch tiếng chó sủa và sách không viết cho FDE, nhưng mục lục của nó chạm đúng những việc bạn phải lo trước khi rời dự án.

Bản gốc: https://fdetimes.net/vi/sach-khoa-hoc/sach-docs-for-developers-bhatti-corleissen-lambourne-nunez-waterhouse/

Một cuốn sách nghiêm túc về tài liệu kỹ thuật lại chọn ví dụ xuyên suốt là Corg.ly, một API dịch tiếng chó sủa. Đằng sau ví dụ vui ấy là câu hỏi FDE nào cũng phải trả lời: đội khách có chạy được hệ thống khi không có bạn không?

Trong lời tựa, Kelsey Hightower viết rằng nếu lập trình viên là siêu anh hùng của ngành phần mềm thì thiếu tài liệu chính là kryptonite của họ. Thử hình dung thứ kryptonite ấy khi bạn ở chỗ khách: một tin nhắn Slack hỏi "token hết hạn rồi, xoay lại thế nào anh nhỉ?"

Bạn có thể ship đúng hạn và demo thật đẹp. Nhưng nếu mỗi thao tác vận hành đều cần gọi bạn, bạn chưa bàn giao được gì và cũng khó sang khách tiếp theo. Vì thế cuốn sách này đáng đọc với FDE, dù nó không viết cho FDE.

**Điểm mấu chốt:** Nếu khách phải gọi bạn mới chạy được hệ thống, bạn chính là tài liệu còn thiếu.

## Viết cho kỹ sư, nhưng không viết cho công việc tại khách

Jared Bhatti, Zachary Sarah Corleissen và các đồng tác giả viết cuốn này với mục tiêu, như họ nói trên [trang chính thức](https://docsfordevelopers.com), là nhân rộng kinh nghiệm viết tài liệu kỹ thuật nhiều thập kỷ của mình tới những người cần nó nhất.

Podcast Write the Docs nhận xét sách viết riêng cho lập trình viên, đi từ phân tích người đọc đến viết nháp, biên tập và xuất bản.

Bài ra mắt trên trang sách đề ngày 7/10/2021. Bản in lần hai có thêm phần các tác giả gọi là suy ngẫm và lời khuyên về việc dùng AI trong quy trình viết, nên nếu mua, bạn nên chọn bản này.

Giới hạn của sách nằm ở bối cảnh: nó đi theo một đội phần mềm ra mắt sản phẩm mới. Người đọc của một sản phẩm mới ra mắt phần lớn còn là người lạ, còn người đọc của bạn có tên, có chức danh và ngồi cách bạn một cuộc gọi. Đó là lợi thế, vì bạn có thể thử mọi điều mình viết ngay trên người thật.

Vì thế, ba ý dưới đây xuất phát từ các chương của sách, còn việc đem chúng sang chỗ khách là phần bạn phải tự làm. Các ví dụ và phép đo là gợi ý để bạn áp dụng, không phải quy trình in trong sách.

## Ý đầu tiên: không có tài liệu nào viết cho "đội khách"

[Mục lục](https://docsfordevelopers.com/table-of-contents/) mở đầu bằng Chương 1 về hiểu người đọc. Với FDE, đây cũng là chỗ nên bắt đầu, vì "đội khách" không phải một người đọc.

Thử hình dung bạn tích hợp một agent vào hệ thống kho của một công ty logistics. Kỹ sư trực lúc 2 giờ sáng cần các bước rollback, nhà phân tích cần biết từng trường dữ liệu nghĩa là gì, còn quản trị viên IT cần cách xoay token và cấp quyền. Một file README dài 40 trang sẽ làm cả ba thất vọng.

Việc đầu tiên tại khách là ghi ra ba cột: ai đọc, họ cần hoàn thành việc gì, và họ đang ở tình huống nào khi mở tài liệu. Nếu chưa điền được, cuộc discovery của bạn còn thiếu câu hỏi.

## Ý thứ hai: đếm câu hỏi, nhưng đừng tin con số ngay

Chương 8 bàn về thu thập và đưa phản hồi vào tài liệu, còn Chương 9 bàn về đo chất lượng tài liệu. Với FDE, nguồn phản hồi rẻ nhất đang nằm sẵn trong kênh Slack chung với khách.

Lấy một ví dụ giả định: trong 2 tuần, đội khách hỏi bạn 40 câu, và 26 câu xoay quanh ba chủ đề là xoay token, xử lý retry và thay đổi schema.

Vậy 65% khối lượng hỗ trợ đến từ đúng ba trang tài liệu chưa tồn tại. Viết xong ba trang đó, 2 tuần sau số câu hỏi còn 18 thì tổng đã giảm 22 câu, tức 55%. Đó là một con số để báo cáo, nhưng chưa phải bằng chứng.

Đội khách càng quen hệ thống thì càng ít hỏi, dù bạn không viết thêm trang nào. Vì thế hãy tách con số theo chủ đề: nếu ba chủ đề đã viết tụt từ 26 xuống 4 còn các chủ đề khác vẫn giữ 14, tài liệu nhiều khả năng đã có tác dụng.

Nếu mọi chủ đề cùng giảm, có thể đội khách chỉ đơn giản là đã quen việc. Còn nếu trang đã có mà vẫn bị hỏi, hãy kiểm tra xem nó có nằm đúng chỗ và viết đúng cho người đọc không, trước khi viết thêm.

Số câu hỏi vẫn chưa đủ, vì khách có thể ngại hỏi rồi làm sai. Hãy thêm một phép thử: đưa runbook cho một kỹ sư bên khách chưa từng chạm vào hệ thống, ngồi im và ghi lại từng chỗ họ khựng lại. Mỗi lần bạn buột miệng giải thích là một dòng còn thiếu trong tài liệu.

## Ý thứ ba: tài liệu cần người nhận, không chỉ người viết

Chương 11 bàn về bảo trì và ngừng hỗ trợ tài liệu. Với FDE, đây có lẽ là chương khó áp dụng nhất, vì bạn sẽ rời đi còn tài liệu thì ở lại và cũ dần theo từng lần khách đổi cấu hình.

Trước ngày handoff, hãy bảo đảm mỗi tài liệu có tên một người phụ trách bên khách và một ngày rà soát kế tiếp. Trang nào đã lỗi thời thì đánh dấu rõ hoặc gỡ hẳn, vì một runbook sai lúc nửa đêm tệ hơn không có runbook.

Phụ lục A đặt thêm một câu hỏi: khi nào nên thuê chuyên gia viết tài liệu. Câu hỏi này đáng mang vào cuộc họp với khách khi khối tài liệu lớn dần, vì không phải trang nào FDE cũng nên tự giữ đến cùng.

## Đọc theo thứ tự nào?

Sách hợp nhất với kỹ sư đang tự viết tài liệu mà chưa từng được dạy, nhất là người sắp có đợt handoff đầu tiên. Nếu bạn đã là technical writer lâu năm, sách viết cho lập trình viên có lẽ sẽ cho bạn ít điều mới hơn. Đừng đọc tuần tự như giáo trình; hãy đọc theo nhịp của dự án.

| Phần của sách | Lúc cần tại khách | Việc FDE nên làm |
|---|---|---|
| Chương 1: hiểu người đọc | Tuần đầu, song song với discovery | Lập bảng ai đọc, cần làm gì, trong tình huống nào |
| Chương 8: phản hồi | Khi đội khách bắt đầu tự dùng | Gom câu hỏi từ Slack và email vào một danh sách |
| Chương 9: đo chất lượng | Vài tuần trước handoff | Chốt mốc số câu hỏi, chạy phép thử không trợ giúp |
| Chương 11: bảo trì, ngừng hỗ trợ | Trước khi rời dự án | Gán người phụ trách và ngày rà soát |
| Phụ lục A: thuê chuyên gia | Khi tài liệu vượt sức đội dự án | Nêu câu hỏi này với khách |

Phần viết nháp, biên tập và xuất bản thì đọc khi bạn ngồi vào viết trang đầu tiên. Lời khuyên về AI của bản in lần hai nên đọc cùng lúc đó, nếu bạn định dùng mô hình để soạn nháp. Dù dùng công cụ nào, hãy tự chạy lại từng lệnh trong môi trường của khách trước khi giao.

## Biến tài liệu thành bằng chứng trong CV

Kỹ năng này khó thể hiện nếu CV chỉ ghi "viết tài liệu tốt". Một dòng như "Viết runbook cho ba chủ đề bị hỏi nhiều nhất: số câu hỏi về chúng giảm từ 26 xuống 4 sau 2 tuần, và một kỹ sư mới làm theo được mà không cần ai giúp" có sức nặng hơn hẳn, miễn là con số do chính bạn đo.

Chưa có khách thật, bạn vẫn có thể tự viết tài liệu cho một API mã nguồn mở, nhờ một người bạn làm theo và công bố cả bản trước lẫn bản sau.

Khi đọc mô tả công việc FDE, hãy để ý các từ như handoff hay enablement, rồi hỏi nhà tuyển dụng ai giữ tài liệu sau khi FDE rời đi. Nếu họ không trả lời được, nhiều khả năng việc đó sẽ đổ lên đầu bạn.

Bài kiểm tra thật của một deployment không diễn ra khi bạn còn ở đó. Nó diễn ra tuần sau khi bạn rời đi, lúc ai đó bên khách gặp sự cố và mở tài liệu của bạn thay vì mở Slack.

**Thử ngay tuần này:**

- Xuất câu hỏi của đội khách trong 2 tuần gần nhất, xếp theo chủ đề và viết tài liệu cho chủ đề bị hỏi nhiều nhất.
- Nhờ một kỹ sư chưa biết hệ thống làm theo một runbook của bạn, ngồi im quan sát và ghi lại từng chỗ họ khựng lại.
- Thêm dòng người phụ trách và ngày rà soát kế tiếp vào đầu mỗi tài liệu sẽ bàn giao cho khách.

## Nguồn

- [Docs for Developers (trang sách chính thức)](https://docsfordevelopers.com)

- [Table of Contents – Docs for Developers](https://docsfordevelopers.com/table-of-contents/)

- [WTD Episode 35: Docs for Developers book, with Jared Bhatti and Zachary Sarah Corleissen](https://podcast.writethedocs.org/2021/10/31/episode-35-docs-for-developers)