Tài liệu hướng dẫn là một tính năng
Tài liệu hướng dẫn không tách rời khỏi sản phẩm của bạn. Nó là một phần của sản phẩm.
Nhiều nhà phát triển đang tuân theo một quy trình sai lầm:
- Xây dựng tính năng.
- Kiểm thử tính năng.
- Phát hành tính năng.
- Viết tài liệu cho tính năng.
Người dùng không trải nghiệm mã nguồn của bạn. Họ trải nghiệm giao diện, quy trình làm việc và tài liệu hướng dẫn của bạn. Đối với người dùng, tài liệu hướng dẫn chính là một tính năng.
Những người tạo ra sản phẩm thường bỏ qua tài liệu hướng dẫn vì họ đã hiểu rõ sản phẩm. Bạn biết tại sao mình lại đưa ra những quyết định nhất định. Bạn biết API hoạt động như thế nào. Bạn biết các phím tắt.
Người dùng thì không. Những gì có vẻ hiển nhiên với bạn lại là điều bí ẩn đối với họ.
Hãy coi những câu hỏi lặp đi lặp lại là nợ tài liệu (documentation debt). Nếu mọi người hỏi cùng một câu hỏi đến lần thứ hai, bạn đang gặp vấn đề. Hoặc là sản phẩm của bạn gây khó hiểu, hoặc là tài liệu của bạn chưa đầy đủ. Đôi khi bạn cần sửa lại API. Nhưng thường thì, bạn cần sửa lại tài liệu.
Tài liệu hướng dẫn tốt giúp giảm thiểu trở ngại. Nó trả lời nhanh chóng các câu hỏi sau:
- Đây là gì?
- Tại sao tôi nên sử dụng nó?
- Làm thế nào để bắt đầu?
- Cách tiếp cận tốt nhất là gì?
- Một ví dụ đơn giản là gì?
Mục tiêu không phải là sự đầy đủ. Mục tiêu là tạo ra đà phát triển (momentum).
Tài liệu hướng dẫn tuyệt vời sẽ dạy về các khuôn mẫu (patterns) và ý đồ (intent). Nó giải thích tại sao một framework lại hoạt động theo một cách nhất định. Điều này giúp người dùng làm việc hiệu quả hơn.
Tài liệu hướng dẫn tác động đến doanh nghiệp của bạn theo những cách âm thầm:
- Tỷ lệ áp dụng.
- Tốc độ làm quen (onboarding).
- Chi phí hỗ trợ.
- Sự phát triển của cộng đồng.
- Trải nghiệm nhà phát triển.
Bạn không dễ dàng nhận thấy tác động của bộ tài liệu tốt. Nhưng bạn sẽ nhận ra ngay lập tức sự thiếu vắng của một bộ tài liệu tồi.
Hãy nhớ rằng tài liệu hướng dẫn cũng dành cho chính bạn. Nó lưu giữ kiến thức cho phiên bản tương lai của chính bạn. Nó ghi lại các quyết định để bạn không phải mất công tìm lại câu trả lời sau nhiều tháng.
Chất lượng sản phẩm và chất lượng tài liệu hướng dẫn có mối liên hệ chặt chẽ với nhau.
- Phần mềm gây khó hiểu cần nhiều tài liệu hơn.
- Phần mềm rõ ràng thì cần ít hơn.
- Tài liệu hướng dẫn tốt sẽ làm lộ ra những thiết kế tồi.
Đừng coi tài liệu hướng dẫn là một việc làm thêm sau cùng. Hãy sử dụng nó để buộc bản thân phải tạo ra sự rõ ràng. Sự rõ ràng giúp cải thiện thiết kế của bạn. Thiết kế được cải thiện sẽ giúp nâng cao chất lượng sản phẩm.
Nguồn: https://dev.to/stinklewinks/documentation-is-a-feature-228n