Hướng dẫn viết docs Pancake
Hướng dẫn và Quy tắc chung về viết docs cho Pancake và các ứng dụng.
Last updated
Tiếng Việt 2024
Hướng dẫn và Quy tắc chung về viết docs cho Pancake và các ứng dụng.
Last updated
Hướng dẫn bao gồm thông tin về các loại docs, format chung của một docs, quy chuẩn về hình ảnh sử dụng trong quá trình viết docs, một số lưu ý chung và tiêu chí đánh giá docs thành công.
Đây là loại hướng dẫn áp dụng cho những cài đặt có nhiều bước, phải chuyển qua nhiều màn hình/view khác nhau.
Nên sử dụng "Bước 1, Bước 2,..." để dễ dàng đề cập lại đến bước này tại những phần kế tiếp nếu cần.
Hướng dẫn chi tiết các tuỳ chọn cài đặt áp dụng khi màn hình có nhiều lựa chọn dạng bật/tắt, ví dụ cài đặt chung, giải thích các cài đặt trong view, không phải chuyển màn hình.
Một docs cơ bản cần bao gồm những phần sau, có thể tuỳ theo mục đích, trường hợp để biến đổi thêm/bớt linh hoạt nhưng vẫn cần giữ nguyên cấu trúc. Những phần Optional là không bắt buộc, tuy nhiên nên có để người đọc có trải nghiệm tốt hơn.
Nên đặt tiêu đề ngắn gọn, tập trung vào keyword mà người đọc thường tìm kiếm. Ưu tiên sử dụng Động từ.
Ví dụ: Đăng nhập Pancake. Kết nối Facebook với Pancake. Tạo gói cước Pancake.
Tiêu đề phụ để giải thích ngắn gọn về tính năng, về nội dung chính của mục. Tiêu đề phụ chi tiết hơn so với tiêu đề chính.
Ví dụ: Định nghĩa và cách sử dụng chế độ gộp trang Pancake. Tạo gói cước Pancake như thế nào. Cách cài đặt, thêm mới, chỉnh sửa câu trả lời nhanh trên Pancake.
OptionalMô tả chi tiết dùng để giải thích cụ thể về mục đích tính năng.
Ví dụ: Nhóm gộp trang sử dụng khi bạn có nhiều trang, chia thành nhiều nhóm trang với mục đích khác nhau. Sử dụng nhóm gộp trang để truy cập chế độ gộp trang nhanh hơn.
OptionalYêu cầu liệt kê các yêu cầu cần có trước khi thực hiện cài đặt theo hướng dẫn. Nếu không có đủ tài nguyên theo yêu cầu, người dùng sẽ không thể thực hiện được.
Ví dụ: Cần có tài khoản BM đã xác minh. Cần có tối thiểu 2 page để có thể sử dụng chế độ gộp trang.
OptionalMột số yêu cầu để thống nhất về cách sử dụng hình ảnh trong docs.
Ảnh cần có mô tả.
Chụp toàn màn hình (màn cỡ nhỏ 13 - 14inch).
Khi cần Highlight một mục, highlight bằng đường màu đỏ.
Trên một ảnh, nếu cần thể hiện nhiều bước, sử dụng mũi tên.
Note thông tin (i xanh lam): Cung cấp thêm thông tin về nội dung hiện tại. Với note này thì thông tin chỉ mang tính bổ sung, không quan trọng, không ảnh hưởng tới các mục khác.
Note cảnh báo (i vàng): Cung cấp thêm thông tin nhưng mang tính nghiêm trọng hơn. Có thể là những cảnh báo về tính năng không hoạt động, tính năng chưa hoàn thiện. Không ảnh hưởng quá nhiều tới khách hàng.
Note đặc biệt lưu ý (i đỏ): Thông tin nghiêm trọng, bắt buộc phải thực hiện. Ví dụ cảnh báo về mất dữ liệu,...
Ưu tiên diễn đạt bằng hình ảnh, hạn chế sử dụng từ chuyên ngành.
Trên một màn hình chức năng, thứ tự ưu tiên viết docs là từ trên xuống dưới, từ trái qua phải.
sơ đồ phân rã tính năng trước khi viết docs.Chuẩn hoá bản tiếng Việt + tiếng Anh, các ngôn ngữ khác bạn phụ trách thị trường chịu trách nhiệm dịch.
Cần có ví dụ ngay tại những phần cài đặt khó hiểu. Ví dụ đặt trong thẻ Quote, chữ nghiêng.
Sử dụng câu hỏi đơn giản để mở đầu, theo cách khách hàng hay hỏi.
Thống nhất danh xưng là BẠN
Đánh giá hướng dẫn bằng cách đưa hướng dẫn cho một người chưa từng sử dụng, nếu người đó có thể hiểu và thực hiện 90% phần cài đặt mà không cần hỗ trợ là docs thành công.
