Các quy tắc để viết tutorial phần mềm

xguru · 2025-01-15T10:41:02+09:00

Phần lớn các tutorial phần mềm bỏ sót những chi tiết quan trọng hoặc chứa các giả định ẩn không phù hợp với kỳ vọng của người đọc, khiến họ không thể tái hiện lại quy trình Chỉ cần làm theo một vài quy tắc đơn giản, việc viết một tutorial xuất sắc sẽ dễ hơn bạn nghĩ Quy tắc Viết cho người mới bắt đầu Viết tiêu đề hứa hẹn một kết quả rõ ràng Giải thích mục tiêu ngay trong phần mở đầu Cho xem trước kết quả cuối cùng Viết code snippet có thể copy/paste Dùng cờ dài trong câu lệnh Tách giá trị tùy biến của người dùng khỏi logic có thể tái sử dụng Giảm công sức cho người đọc Viết sao cho code luôn ở trạng thái hoạt động Chỉ dạy một chủ đề Ưu tiên sự rõ ràng hơn là trang trí Tối thiểu hóa dependency Chỉ rõ tên file một cách rõ ràng Dùng tiêu đề nhất quán và giàu tính mô tả Chứng minh rằng giải pháp hoạt động Liên kết tới ví dụ hoàn chỉnh Viết cho người mới bắt đầu Sai lầm phổ biến nhất của tutorial là giải thích các khái niệm ở mức người mới bằng thuật ngữ ở mức chuyên gia. Phần lớn những người tìm tutorial đều là người mới bắt đầu. Họ có thể không mới với lập trình, nhưng lại là người mới trong lĩnh vực họ đang muốn học Hãy viết cho người mới bắt đầu và tránh dùng thuật ngữ ở mức chuyên gia Tránh các từ ngữ khó và viết bằng ngôn ngữ đơn giản mà người đọc có thể hiểu Ví dụ, trong tutorial React, hãy dùng mô tả như "tạo một trang web đơn giản với React" thay vì "JSX transpilation" Viết tiêu đề hứa hẹn một kết quả rõ ràng Tiêu đề phải truyền đạt cụ thể người đọc sẽ học được gì qua tutorial Tránh các tiêu đề không rõ ràng hoặc mơ hồ, và mô tả rõ kết quả kỳ vọng Ví dụ: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView" Giải thích mục tiêu ngay trong phần mở đầu Khi người đọc click vào tutorial, điều đó có nghĩa là họ quan tâm đến điều bạn nói. Nhưng bạn vẫn phải thuyết phục họ tiếp tục đọc Có hai điều người đọc muốn biết Họ có nên quan tâm đến công nghệ này không? Nếu có quan tâm, tutorial này có phù hợp với họ không? Hãy giải thích ngắn gọn trong phần mở đầu về tầm quan trọng của công nghệ và tính hữu ích của tutorial Cung cấp thông tin hữu ích để khiến người đọc quan tâm, và tránh những mô tả mơ hồ Ví dụ: tutorial Docker nên giải thích rõ Docker giải quyết vấn đề gì và kết quả mong đợi là gì Cho xem trước kết quả cuối cùng Càng sớm càng tốt, hãy cho người đọc xem demo hoặc ảnh chụp màn hình của thứ họ sẽ tạo ra thông qua tutorial Hãy cho thấy kết quả cuối cùng ngay ở phần đầu tutorial để làm rõ mục tiêu Ví dụ: cung cấp ảnh chụp màn hình của sản phẩm hoàn chỉnh, UI, ví dụ hoạt động, v.v. Viết code snippet có thể copy/paste Hãy viết sao cho người đọc có thể dễ dàng sao chép code và dán vào editor hoặc terminal để chạy Loại bỏ các yếu tố không cần thiết như ký tự dấu nhắc terminal $ Dùng cờ non-interactive để đơn giản hóa câu lệnh, và dùng && để dừng khi gặp lỗi Dùng cờ dài trong câu lệnh Trong câu lệnh, hãy dùng cờ dài có ý nghĩa rõ ràng thay vì cờ ngắn để cả người mới bắt đầu cũng dễ hiểu -r thay vì --recursive Tách giá trị tùy biến của người dùng khỏi logic có thể tái sử dụng Trong code, hãy tách rõ các giá trị người dùng cần sửa và phần code không nên sửa Dùng biến môi trường để định nghĩa các giá trị tùy biến và tăng tính dễ đọc của code Giảm công sức cho người đọc Hãy tôn trọng thời gian của người đọc để họ có thể thích tutorial của bạn hơn Thay các công việc tẻ nhạt bằng snippet lệnh để họ không phải làm thủ công Ví dụ: thay vì sửa file bằng tay, hãy giải quyết bằng câu lệnh Viết sao cho code luôn ở trạng thái hoạt động Code ví dụ phải luôn có thể chạy được và vẫn ở trạng thái hoạt động ngay cả trong các bước trung gian Code sai hoặc ví dụ không chạy được sẽ gây bối rối cho người đọc Chỉ dạy một chủ đề Tutorial nên xoay quanh một chủ đề duy nhất và không trộn lẫn các công nghệ không liên quan Ví dụ, đừng thêm các công nghệ AI không cần thiết vào một tutorial giải thích tính năng tìm kiếm Ưu tiên sự rõ ràng hơn là trang trí Người đọc không quan tâm ứng dụng mẫu có đẹp mắt hay không Hãy giảm thiểu CSS hoặc các yếu tố thiết kế không cần thiết và tập trung vào khái niệm cốt lõi Thay vì ví dụ phức tạp, hãy dùng code đơn giản để truyền đạt khái niệm một cách rõ ràng Tối thiểu hóa dependency Hãy giảm số dependency mà người đọc phải cài đặt để tăng khả năng tiếp cận của tutorial Chỉ rõ các dependency bắt buộc và nêu rõ phiên bản cụ thể Chỉ rõ tên file một cách rõ ràng Hãy hướng dẫn chính xác đường dẫn file và nội dung mà người đọc cần sửa Ví dụ, thay vì nói "thêm cấu hình vào file config", hãy cung cấp đầy đủ đường dẫn file và đoạn code cụ thể cần chỉnh ở dòng nào Dùng tiêu đề nhất quán và giàu tính mô tả Dùng các heading có cấu trúc để người đọc dễ quét tutorial Dùng tiêu đề để cấu trúc tutorial và viết tiêu đề sao cho phản ánh được cấu trúc logic Giữ định dạng, ngôi viết và thì của tiêu đề nhất quán Chứng minh rằng giải pháp hoạt động Nếu tutorial dạy cài đặt công cụ hoặc tích hợp nhiều thành phần, hãy cho thấy cách sử dụng kết quả Hãy cho người đọc thấy trực quan kết quả hoạt động của công cụ đã được cài đặt và tích hợp Ví dụ, hiển thị trang thành công của nginx và cung cấp cách kiểm tra qua URL Liên kết tới ví dụ hoàn chỉnh Hãy liên kết tới repository chứa toàn bộ code của tutorial để người đọc có thể xem được toàn bộ luồng Chia code của từng bước thành các git branch riêng để người đọc có thể theo dõi từng bước

(refactoringenglish.com)

70 điểm bởi xguru 2025-01-15 | 11 bình luận | Chia sẻ qua WhatsApp

Phần lớn các tutorial phần mềm bỏ sót những chi tiết quan trọng hoặc chứa các giả định ẩn không phù hợp với kỳ vọng của người đọc, khiến họ không thể tái hiện lại quy trình
Chỉ cần làm theo một vài quy tắc đơn giản, việc viết một tutorial xuất sắc sẽ dễ hơn bạn nghĩ

Quy tắc

Viết cho người mới bắt đầu
Viết tiêu đề hứa hẹn một kết quả rõ ràng
Giải thích mục tiêu ngay trong phần mở đầu
Cho xem trước kết quả cuối cùng
Viết code snippet có thể copy/paste
Dùng cờ dài trong câu lệnh
Tách giá trị tùy biến của người dùng khỏi logic có thể tái sử dụng
Giảm công sức cho người đọc
Viết sao cho code luôn ở trạng thái hoạt động
Chỉ dạy một chủ đề
Ưu tiên sự rõ ràng hơn là trang trí
Tối thiểu hóa dependency
Chỉ rõ tên file một cách rõ ràng
Dùng tiêu đề nhất quán và giàu tính mô tả
Chứng minh rằng giải pháp hoạt động
Liên kết tới ví dụ hoàn chỉnh

Viết cho người mới bắt đầu

Sai lầm phổ biến nhất của tutorial là giải thích các khái niệm ở mức người mới bằng thuật ngữ ở mức chuyên gia. Phần lớn những người tìm tutorial đều là người mới bắt đầu.
- Họ có thể không mới với lập trình, nhưng lại là người mới trong lĩnh vực họ đang muốn học
Hãy viết cho người mới bắt đầu và tránh dùng thuật ngữ ở mức chuyên gia
Tránh các từ ngữ khó và viết bằng ngôn ngữ đơn giản mà người đọc có thể hiểu
Ví dụ, trong tutorial React, hãy dùng mô tả như "tạo một trang web đơn giản với React" thay vì "JSX transpilation"

Viết tiêu đề hứa hẹn một kết quả rõ ràng

Tiêu đề phải truyền đạt cụ thể người đọc sẽ học được gì qua tutorial
Tránh các tiêu đề không rõ ràng hoặc mơ hồ, và mô tả rõ kết quả kỳ vọng
- Ví dụ: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Giải thích mục tiêu ngay trong phần mở đầu

Khi người đọc click vào tutorial, điều đó có nghĩa là họ quan tâm đến điều bạn nói. Nhưng bạn vẫn phải thuyết phục họ tiếp tục đọc
Có hai điều người đọc muốn biết
- Họ có nên quan tâm đến công nghệ này không?
- Nếu có quan tâm, tutorial này có phù hợp với họ không?
Hãy giải thích ngắn gọn trong phần mở đầu về tầm quan trọng của công nghệ và tính hữu ích của tutorial
Cung cấp thông tin hữu ích để khiến người đọc quan tâm, và tránh những mô tả mơ hồ
- Ví dụ: tutorial Docker nên giải thích rõ Docker giải quyết vấn đề gì và kết quả mong đợi là gì

Cho xem trước kết quả cuối cùng

Càng sớm càng tốt, hãy cho người đọc xem demo hoặc ảnh chụp màn hình của thứ họ sẽ tạo ra thông qua tutorial
- Hãy cho thấy kết quả cuối cùng ngay ở phần đầu tutorial để làm rõ mục tiêu
Ví dụ: cung cấp ảnh chụp màn hình của sản phẩm hoàn chỉnh, UI, ví dụ hoạt động, v.v.

Viết code snippet có thể copy/paste

Hãy viết sao cho người đọc có thể dễ dàng sao chép code và dán vào editor hoặc terminal để chạy
Loại bỏ các yếu tố không cần thiết như ký tự dấu nhắc terminal $
Dùng cờ non-interactive để đơn giản hóa câu lệnh, và dùng && để dừng khi gặp lỗi

Dùng cờ dài trong câu lệnh

Trong câu lệnh, hãy dùng cờ dài có ý nghĩa rõ ràng thay vì cờ ngắn để cả người mới bắt đầu cũng dễ hiểu
- -r thay vì --recursive

Tách giá trị tùy biến của người dùng khỏi logic có thể tái sử dụng

Trong code, hãy tách rõ các giá trị người dùng cần sửa và phần code không nên sửa
Dùng biến môi trường để định nghĩa các giá trị tùy biến và tăng tính dễ đọc của code

Giảm công sức cho người đọc

Hãy tôn trọng thời gian của người đọc để họ có thể thích tutorial của bạn hơn
Thay các công việc tẻ nhạt bằng snippet lệnh để họ không phải làm thủ công
- Ví dụ: thay vì sửa file bằng tay, hãy giải quyết bằng câu lệnh

Viết sao cho code luôn ở trạng thái hoạt động

Code ví dụ phải luôn có thể chạy được và vẫn ở trạng thái hoạt động ngay cả trong các bước trung gian
Code sai hoặc ví dụ không chạy được sẽ gây bối rối cho người đọc

Chỉ dạy một chủ đề

Tutorial nên xoay quanh một chủ đề duy nhất và không trộn lẫn các công nghệ không liên quan
Ví dụ, đừng thêm các công nghệ AI không cần thiết vào một tutorial giải thích tính năng tìm kiếm

Ưu tiên sự rõ ràng hơn là trang trí

Người đọc không quan tâm ứng dụng mẫu có đẹp mắt hay không
Hãy giảm thiểu CSS hoặc các yếu tố thiết kế không cần thiết và tập trung vào khái niệm cốt lõi
Thay vì ví dụ phức tạp, hãy dùng code đơn giản để truyền đạt khái niệm một cách rõ ràng

Tối thiểu hóa dependency

Hãy giảm số dependency mà người đọc phải cài đặt để tăng khả năng tiếp cận của tutorial
Chỉ rõ các dependency bắt buộc và nêu rõ phiên bản cụ thể

Chỉ rõ tên file một cách rõ ràng

Hãy hướng dẫn chính xác đường dẫn file và nội dung mà người đọc cần sửa
Ví dụ, thay vì nói "thêm cấu hình vào file config", hãy cung cấp đầy đủ đường dẫn file và đoạn code cụ thể cần chỉnh ở dòng nào

Dùng tiêu đề nhất quán và giàu tính mô tả

Dùng các heading có cấu trúc để người đọc dễ quét tutorial
Dùng tiêu đề để cấu trúc tutorial và viết tiêu đề sao cho phản ánh được cấu trúc logic
Giữ định dạng, ngôi viết và thì của tiêu đề nhất quán

Chứng minh rằng giải pháp hoạt động

Nếu tutorial dạy cài đặt công cụ hoặc tích hợp nhiều thành phần, hãy cho thấy cách sử dụng kết quả
- Hãy cho người đọc thấy trực quan kết quả hoạt động của công cụ đã được cài đặt và tích hợp
Ví dụ, hiển thị trang thành công của nginx và cung cấp cách kiểm tra qua URL

Liên kết tới ví dụ hoàn chỉnh

Hãy liên kết tới repository chứa toàn bộ code của tutorial để người đọc có thể xem được toàn bộ luồng
Chia code của từng bước thành các git branch riêng để người đọc có thể theo dõi từng bước

11 bình luận

godogi7 2025-02-12

Để tham khảo

wedding 2025-01-16

Cái này xin phép đặt gạch!

ilikeall 2025-01-16

Bài viết hay đấy.

halfenif 2025-01-16

Gần đây tôi đã thử làm theo tutorial của dagster và thấy nó được làm rất tốt.

https://courses.dagster.io/

aer0700 2025-01-16

Tôi đã xem qua tutorial của Dagster và thấy nó cực kỳ tốt.
Tutorial của Django thì nội dung rất đầy đặn, nhưng quá dài nên cá nhân tôi không thích lắm. Giá mà chia nhỏ ra thì tốt hơn.

savvykang 2025-01-16

Django cũng là một ví dụ về tutorial được viết rất tốt: https://docs.djangoproject.com/en/5.1/intro/tutorial01/

jhj0517 2025-01-16

Sử dụng ngôn ngữ đơn giản & hiển thị kết quả cuối cùng trước tiên.

aer0700 2025-01-15

Thay vì chỉ ra cách dùng cơ bản nhàm chán của framework,
thỉnh thoảng lại có những tài liệu hướng dẫn chỉ muốn cho thấy framework này ngầu đến mức nào.
Tôi rất ghét khi vào mục Get started mà cái được ghi là tutorial dùng cơ bản lại là một tài liệu dài tới 10 trang.

beenzinozino 2025-01-16

Mọi người đều ghê gớm quá...

savvykang 2025-01-15

https://tanstack.com/table/latest/docs/introduction

nono9633 2025-01-15

https://github.com/tmux/tmux/wiki/Getting-Started