1. Giới thiệu
Không cần biết tính năng/sản phẩm của bạn làm ra tốt đến đâu, nếu document về nó không tốt hoặc khó hiểu, thì cũng chẳng ai sử dụng nó. Để viết được một document tốt, thay vì nỗ lực viết một cách lan man, chúng ta cần viết đúng cách. Ta cần hiểu và làm rõ 4 loại tài liệu sau, chúng đại diện cho mục đích và chức năng khác nhau. Nắm rõ được chúng sẽ giúp chúng ta viết documents tường minh và hiệu quả hơn.
-
Tutorials Giúp người đọc: học hỏi về một kiến thức/ bài học mới Nội dung: là những bài học, hướng dẫn Ví dụ: Hướng dẫn một cậu bé làm thế nào để nấu ăn
-
How to guides: Giúp người đọc: giải quyết được một vấn đề Nội dung: các bước giải quyết vấn đề Ví dụ: Một công thức nấu ăn
-
Technical reference: Giúp người đọc: có thêm thông tin về một vấn đề Nội dung: mô tả nội dung Ví dụ: 1 chương trong quyển bách khoa toàn thư
-
Explanation: Giúp người đọc: hiểu về một vấn đề nào đó Nội dung: giải thích chi tiết về 1 vấn đề Ví dụ: 1 bài báo về
Một vài điểm giao thoa giữa các loại tài liệu: tutorials và how to guides: quan tâm đến việc mô tả các bước thực tế how to guides và reference guide: là những gì ta cần khi làm việc reference guide và explanation đều liên quan đến lý thuyết tutorials và explanation: hữu ích chúng ta học một điều gì đó mới, thay vì thực sự làm việc
2. Tutorials
Tutorials là những bài học giúp người đọc đi qua một loạt các bước để hoàn thành một vấn đề/ dự án nào đó.
Cách để viết một document tutorials hiệu quả:
- Người đọc cần sẽ được làm mọi thứ trực tiếp theo hướng dẫn của bạn, bao gồm một loạt các tool và thao tác, từ đơn giản nhất khi bắt đầu đến phức tạp hơn.
- Tập trung vào quá trình, các bước thao t, thay vì kết quả đạt được
- Đối tượng đọc là những người mới, không có kinh nghiệm, nên cần được hướng dẫn tỉ mỉ
- Chắc chắn rằng turorial hoạt động đúng. Thử làm lại theo chính xác những gì bạn mô tả trong tutorial trên nhiều môi trường để recheck xem có bất kỳ lỗi phát sinh nào không, nếu có cần note lại chi tiết trong tài liệu
- Đảm bảo người đọc có thể nhìn thấy được kết quả mà họ đạt được sau khi hoàn thành tutorials
- Tutorial phải được viết rõ ràng, chi tiết
- Chỉ giải thích khi cần thiết, không giải thích những kiến thức khômh liên quan đến tutorials
- Chỉ tập trung vào các bước người đọc cần làm, tránh lan man
3. How-to guides
How to guides: đưa người đọc qua các bước cần thiết để giải quyết vấn đề trong thực tế. Chúng ta những công thức, chỉ dẫn, giúp người đọc đạt được một kết quả cụ thể
How to guides khác với tutorial như thế nào: Tutorial: dành cho những beginner, những người chưa có bất kỳ kiến thức, kinh nghiệm nào How-to guide: dành cho những người đã có một số kinh nghiệm cụ thể. Bạn có thể giả định người đọc đã có một số kiến thức, hiểu biết cơ bản cũng như cách sử dụng một vài công cụ cơ bản
Cách để viết một document how-to-guides hiệu quả:
- Cung cấp một list các bước để người đọc dễ hình dung.
- Tập trung vào việc giúp người đọc đạt được kết quả cụ thể
- Chỉ dẫn cho người đọc trả lời được câu hỏi: “tôi phải làm … như thế nào?”
- Không giải thích các khái niệm cơ bản. Nếu cần có thể đính kèm link.
- Nếu có thể, cho phép người đọc nhiều option để lựa chọn ở từng bước, giúp docs trở nên linh động và dễ tuỳ biến hơn, không bị quá tập trung vào chi tiết.
- Đặt tên title document dễ hiểu, giúp người đọc hình dung ra mục đích của document. Ví dụ: “How to…”
4. Reference guides
Reference guides là các mô tả kỹ thuật của máy móc và cách vận nó. Reference guides định hướng thông tin đơn giản và đi thẳng vào vấn đề.
Cách để viết một document Reference guides hiệu quả:
- Cấu trúc tài liệu xung quanh code: Cung cấp cho reference guides cấu trúc giống như codebase để người dùng có thể điều hướng cả mã và tài liệu cho nó cùng một lúc.
- Nhất quán: Trong reference guides, cấu trúc, giọng điệu, định dạng tất cả phải nhất quán - nhất quán như trong bách khoa toàn thư hoặc từ điển.
- Không làm gì ngoài việc mô tả: Công việc duy nhất của reference là mô tả, càng rõ ràng và đầy đủ càng tốt. Bất cứ điều gì khác (giải thích, thảo luận, hướng dẫn, suy đoán, ý kiến) không chỉ gây xao nhãng mà còn khiến việc sử dụng và bảo trì khó khăn hơn.
- Chính xác: Những mô tả này phải chính xác và được cập nhật. Bất kỳ sự khác biệt nào giữa máy móc và mô tả của bạn về nó chắc chắn sẽ khiến người dùng lạc lối.
5. Explanation
Explanation: Giải thích, hoặc thảo luận, làm rõ và sáng tỏ một chủ đề cụ thể. Chúng mở rộng phạm vi bao quát của tài liệu về một chủ đề.
Cách để viết một document Explanation hiệu quả:
- Cung cấp ngữ cảnh: Explanation là nơi dành cho nền tảng và ngữ cảnh - ví dụ: Biểu mẫu web và cách chúng được xử lý trong Django hoặc Tìm kiếm trong Django CMS.
- Thảo luận về các lựa chọn thay thế và ý kiến: Explanation có thể xem xét các lựa chọn thay thế hoặc nhiều cách tiếp cận khác nhau cho cùng một câu hỏi.
- Không hướng dẫn, hoặc cung cấp tài liệu tham khảo kỹ thuật: Explanation nên làm những việc mà các phần khác của tài liệu không làm. Nó không phải là nơi giải thích để hướng dẫn người dùng cách làm điều gì đó.