Viết ghi chú phát hành cho người dùng thay vì chép danh sách commit

Ghi chú phát hành cần giúp người dùng quyết định có sử dụng thay đổi, sửa quy trình hay liên hệ hỗ trợ không. Danh sách tiêu đề phiếu nội bộ hiếm khi trả lời được các câu hỏi đó. Bắt đầu từ thay đổi có thể quan sát và hành động cần làm. Giữ liên kết kỹ thuật để truy vết, nhưng đừng buộc khách hàng tự dịch thuật ngữ triển khai thành hệ quả nghiệp vụ.

Tách gói phát hành khỏi phần giải thích

GitHub mô tả release là cách đóng gói phần mềm cùng ghi chú phát hành và liên kết tới tệp nhị phân.[4] Cơ chế đó cung cấp nơi đặt lời giải thích, không quyết định chi tiết nào phù hợp với khách hàng. Coi danh sách commit tự sinh là đầu vào biên tập, không phải thông điệp cuối cùng.

Nhóm thay đổi theo đối tượng hoặc tác vụ nếu cách đó giúp tìm thông tin. Phân biệt hành vi mới, hành vi sửa lỗi, chuyển đổi bắt buộc và giới hạn đã biết. Đừng gọi mọi sửa nhỏ là cải tiến mà không giải thích người dùng sẽ thấy gì khác. Bỏ thay đổi cấu trúc mã nội bộ nếu nó không tạo hệ quả đáng kể cho người dùng.

Viết từng mục để người đọc có thể hành động

Với thay đổi quan trọng, nêu vai trò chịu ảnh hưởng, hành vi trước nếu cần, hành vi mới và việc cần làm. Giải thích thay đổi áp dụng cho tất cả hay chỉ nhóm đã bật tính năng. Không mô tả mức sẵn có rộng hơn phạm vi phát hành thực tế.

Dùng các phép kiểm tra sau trước khi duyệt bản dành cho khách hàng.

• Nêu tác vụ người dùng thay vì chép tiêu đề phiếu nội bộ.
• Cho biết có cần đổi thiết lập hoặc làm lại công việc không.
• Chỉ rõ giới hạn theo vai trò, gói dịch vụ hoặc nhóm triển khai nếu có.
• Liên kết hướng dẫn khi thay đổi cần nhiều bước thực hiện.
• Đưa giới hạn đã biết và kênh hỗ trợ phù hợp vào ghi chú.

Ví dụ giả định: lưu bộ lọc xuất báo cáo

Trong ví dụ giả định về công cụ báo cáo, lịch sử triển khai nhắc tới lưu truy vấn và cập nhật cấu hình. Ghi chú cho người dùng lại giải thích chuyên viên có thể lưu bộ lọc xuất dữ liệu để dùng lại, nút lưu nằm ở đâu và các lần xuất hiện tại có giữ nguyên hành vi không.

Nếu bộ lọc đã lưu ban đầu chỉ dành cho nhóm thử nghiệm, ghi chú nói rõ. Nếu chưa lưu được thứ tự cột, giới hạn đó xuất hiện cạnh mô tả tính năng. Khách hàng có thể quyết định tính năng có hỗ trợ tác vụ của mình không mà không cần giải mã thuật ngữ hoặc tưởng rằng chức năng rộng hơn thực tế.

Kiểm tra đúng trước khi trau chuốt giọng văn

Nhờ đại diện sản phẩm, triển khai và hỗ trợ đối chiếu ghi chú với bản phát hành thực. Kiểm tra hành vi trên đúng bản dựng, nhất là hướng dẫn làm đổi dữ liệu hoặc bỏ lựa chọn cũ. Không đưa thông tin khách hàng riêng tư, cấu hình kỹ thuật nhạy cảm hay lời hứa tương lai chưa chắc chắn vào nội dung công khai.

Quá nhiều chi tiết có thể che mất hành động bắt buộc quan trọng. Quá ít khiến người dùng không chuẩn bị được. Đặt hành động đáng chú ý trước và dẫn tới hướng dẫn sâu hơn. Với lần phát hành kế tiếp, viết lại một mục kỹ thuật thành giải thích theo tác vụ. Sau đó hỏi người ngoài nhóm triển khai họ sẽ làm gì khác sau khi đọc.