Technical Writing One và Two: hai khoá viết miễn phí của Google mà FDE nên học

Thử hình dung câu này nằm trong một email bàn giao: “Chứng chỉ SSL sẽ được gia hạn trước ngày 15.” Nghe thì gọn gàng. Nhưng đến ngày 16, đội của bạn và đội khách hàng có thể cùng phát hiện ra rằng không bên nào nghĩ mình là người phải gia hạn.

Google dạy kỹ sư tránh đúng kiểu lỗi này trong hai khoá Technical Writing One và Technical Writing Two. Cả hai khoá đều miễn phí, nằm trên trang Google for Developers (developers.google.com/tech-writing). Người học không nhất thiết phải là technical writer chuyên nghiệp: khoá nhắm tới software engineer, sinh viên khoa học máy tính và những vai trò gần đó như product manager.

Thử hình dung đợt deployment kết thúc và bạn chuyển sang dự án khác. Spec, runbook và email bàn giao ở lại, và đội khách hàng phải tự vận hành hệ thống chỉ dựa vào những gì bạn viết. Nếu tài liệu buộc họ phải gọi lại để hỏi thì đợt triển khai đó chưa thật sự xong.

Vì sao Google dạy kỹ sư tự viết?

Một bài trên tcworld của Dirk Göhmann, đăng tháng 3/2022, giải thích lý do khá thẳng: nhu cầu tài liệu lớn hơn nhiều so với số technical writer hiện có. Vì không đủ người viết hộ, kỹ sư phải tự viết.

Trong bài đăng ngày 9/7/2020 trên Google Developers Blog, technical writer James Scott nói thêm một ý: khi làm việc từ xa ngày càng phổ biến, tài liệu tốt càng quan trọng vì nó giúp kỹ sư làm việc độc lập.

Với FDE, ý này còn đúng hơn. Lúc họ cần một câu trả lời, người viết tài liệu thường không còn ngồi cạnh để giải thích.

Theo nhật ký thay đổi chính thức, cả hai khoá được công bố ngày 24/2/2020. Lần cập nhật gần nhất của Technical Writing Two là ngày 15/4/2024, khi mỗi bài tập được thêm một slide tóm tắt. Mỗi khoá có hai phần: bài tự học trước buổi học, và buổi học trên lớp với người hướng dẫn và các học viên khác.

Technical Writing One: hai ý đáng giữ

Technical Writing One là khoá nền tảng, dạy cách viết tài liệu kỹ thuật rõ ràng hơn. Theo trang giới thiệu, người học chỉ cần biết viết tiếng Anh ở mức cơ bản.

Ý thứ nhất là xác định người đọc theo thứ họ còn thiếu. Bài về người đọc (audience) nhấn mạnh rằng chức danh chưa đủ để mô tả một người đọc. Tài liệu phải cung cấp những thông tin người đọc cần mà họ chưa có. Bài học còn cảnh báo rằng người giỏi một lĩnh vực rất dễ quên rằng người mới không biết những điều mình đã biết.

Ví dụ, hai kỹ sư data ở phía khách hàng có cùng chức danh nhưng chưa chắc đã cần cùng một tài liệu. Một người đã dùng hệ thống message queue mà bạn chọn, người kia chưa bao giờ dùng. Trước khi viết, bạn nên ghi ra ba điều người đọc chưa biết rồi kiểm tra xem tài liệu đã giải thích đủ cả ba chưa.

Ý thứ hai là dùng thể chủ động. Bài về thể chủ động (active voice) khuyên viết chủ động là chính. Lý do: có những câu bị động bỏ hẳn người thực hiện, khiến người đọc phải đoán ai là người làm. Câu chứng chỉ SSL ở đầu bài là một ví dụ. Viết lại thành “Đội hạ tầng của anh Minh gia hạn chứng chỉ SSL trước ngày 15”, câu chỉ dài thêm vài chữ nhưng đã có người chịu trách nhiệm.

Technical Writing Two: dành cho tài liệu dài

Technical Writing Two là khoá trung cấp. Khoá này dạy tự biên tập, tổ chức tài liệu dài, viết chú thích cho hình minh hoạ, viết tutorial, và gần đây có thêm cách dùng LLM khi viết. Google khuyên những ai chưa học viết kỹ thuật bao giờ nên học One trước.

Ý thứ ba nằm trong bài tổ chức tài liệu dài: phần mở đầu của tài liệu cần nêu rõ tài liệu nói về gì, người đọc cần biết trước điều gì, và tài liệu không nói về gì. Lấy ví dụ một runbook xử lý sự cố pipeline. Bạn có thể mở đầu như sau: runbook này hướng dẫn khởi động lại job ingest bị treo; người đọc cần biết dùng kubectl; runbook không xử lý trường hợp dữ liệu nguồn bị lỗi.

Dòng cuối trông như một lời thanh minh, nhưng thực ra rất hữu dụng. Nó cho kỹ sư trực ca biết khi nào nên dừng đọc và chuyển sang tài liệu khác, thay vì làm theo các bước không dành cho tình huống của họ.

Học xong rồi vẫn sai ở đâu?

Lỗi hay gặp nhất là sửa câu sang thể chủ động nhưng chủ ngữ vẫn mơ hồ. “Phía khách hàng gia hạn chứng chỉ” đúng ngữ pháp, nhưng người đọc vẫn phải đoán là đội nào. Chủ ngữ chỉ có ích khi nó là một tên đội hoặc tên người cụ thể mà ai cũng nhận ra.

Lỗi tiếp theo là viết một bản tài liệu duy nhất cho mọi người có cùng chức danh. Đó đúng là cái bẫy mà bài audience cảnh báo. Cách sửa đơn giản: nếu người đọc có nền tảng khác nhau, tách phần kiến thức nền ra một mục riêng để người đã biết có thể bỏ qua.

Lỗi thứ ba là viết phần mở đầu nhưng lược mất dòng “tài liệu không nói về gì” vì sợ tài liệu trông thiếu sót. Muốn bắt cả ba lỗi, hãy đưa bản nháp cho một đồng nghiệp chưa từng thấy hệ thống, rồi ghi lại mọi chỗ họ phải hỏi bạn.

Nên học theo thứ tự nào?

Nếu bạn đang làm FDE hoặc chuẩn bị chuyển sang vai trò này, hãy học One trước, kể cả khi bạn thấy mình viết đã ổn. Mỗi lần học xong một bài, hãy áp dụng ngay cho một tài liệu thật thay vì để dành đến cuối khoá. Two hữu ích nhất khi bạn sắp phải viết spec hoặc tài liệu bàn giao dài vài trang.

Khả năng viết cũng có thể dùng để chứng minh năng lực khi xin việc. Bạn có thể viết lại một runbook cũ, xoá thông tin mật của khách hàng, rồi đưa bản trước và bản sau vào portfolio. Trên CV, hãy ghi tài liệu đó giúp được việc gì cụ thể.

Khi đi phỏng vấn FDE, hãy mang cặp runbook đó theo. Ở vòng take-home, nộp kèm một README có đủ phần mở đầu ba ý. Ở vòng system design, khi được hỏi sẽ bàn giao cho khách thế nào, mở bản sau ra và chỉ vào dòng “không xử lý trường hợp nào”. Như vậy thuyết phục hơn nhiều so với dòng “kỹ năng giao tiếp tốt”.

Đợt deployment chỉ thực sự xong khi đội khách hàng tự xử lý được sự cố đầu tiên mà không phải gọi cho bạn. Hai khoá học này dạy bạn viết tài liệu để làm được điều đó.