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.

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.

Tổng quan về một số quy tắc chung

1. Các loại hướng dẫn

1.1 Hướng dẫn cấu hình từng bước

Đâ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 cấu hình theo từng bước

1.2 Hướng dẫn chi tiết cài đặt

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.

2. Khung chung cho một docs.

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.

Ví dụ về khung chung cho một docs hướng dẫn

2.1 Tiêu đề

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.

2.2 Tiêu đề phụ

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.

2.3 Mô tả chi tiết - Optional

Mô 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.

2.4 Yêu cầu - Optional

Yê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.

2.5 Nội dung của hướng dẫn

2.6 Gợi ý các cài đặt liên quan - Optional

3. Yêu cầu về hình ảnh khi viết docs

Mộ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.

Yêu cầu về hình ảnh

4. Notes/Hints

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,...

5. Một số lưu ý chung khác

5.1 Ưu tiên hình ảnh, ít chữ, cố gắng diễn đạt ngắn gọn, dễ hiểu, hạn chế sử dụng từ chuyên ngành.

Ưu tiên diễn đạt bằng hình ảnh, hạn chế sử dụng từ chuyên ngành.

5.2 Thứ tự bố cục các mục hướng dẫn: Từ trên xuống dưới, từ trái qua phải theo màn hì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.

5.3 Cần có sơ đồ phân rã tính năng trước khi viết docs.

Ví dụ về sơ đồ phân rã tính năng

• 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.

Ví dụ ở những cài đặt phức tạp

• 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

6. Cách đánh giá hướng dẫ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.