Xác định lý do kinh doanh cho tài liệu của bạn. Mặc dù lý do chức năng của phần mềm là để giúp người dùng hiểu cách sử dụng ứng dụng, nhưng cũng có những lý do khác, chẳng hạn như hỗ trợ tiếp thị phần mềm, nâng cao hình ảnh công ty và đáng chú ý nhất là giảm chi phí hỗ trợ kỹ thuật. Trong một số trường hợp, tài liệu là cần thiết để tuân thủ các quy định nhất định hoặc các yêu cầu pháp lý khác.
Tuy nhiên, trong mọi trường hợp, tài liệu phần mềm không nên thay thế cho thiết kế giao diện kém. Nếu một màn hình ứng dụng yêu cầu hàng loạt tài liệu để giải thích nó, tốt hơn hết bạn nên thay đổi thiết kế màn hình thành một thứ gì đó trực quan hơn.
Hiểu khán giả mà bạn đang viết tài liệu cho họ. Trong hầu hết các trường hợp, người dùng phần mềm có ít kiến thức về máy tính ngoài các tác vụ mà ứng dụng họ sử dụng cho phép họ thực hiện. Có một số cách để xác định cách giải quyết nhu cầu của họ bằng tài liệu của bạn.
- Nhìn vào chức danh công việc mà người dùng tiềm năng của bạn đang nắm giữ. Quản trị viên hệ thống có thể là chuyên gia về một số ứng dụng phần mềm, trong khi nhân viên nhập dữ liệu có nhiều khả năng chỉ biết ứng dụng mà họ hiện đang sử dụng để nhập dữ liệu. Bạn nên lên ý tưởng viết từ tổng thể đến chi tiết, theo từng flows ứng với từng vai trò người dùng. Thí dụ như sau:
- Nhìn vào chính người dùng. Mặc dù chức danh công việc thường chỉ ra những gì mọi người làm, nhưng có thể có sự khác biệt đáng kể về cách sử dụng một số chức danh nhất định trong một tổ chức nhất định. Bằng cách phỏng vấn những người dùng tiềm năng, bạn có thể biết được liệu ấn tượng của bạn về những gì chức danh công việc của họ chỉ ra có chính xác hay không.
- Xem tài liệu hiện có. Tài liệu cho các phiên bản trước của phần mềm, cũng như các thông số kỹ thuật chức năng, cung cấp một số chỉ dẫn về những gì người dùng cần biết để sử dụng chương trình. Tuy nhiên, hãy nhớ rằng người dùng cuối không quan tâm đến cách hoạt động của chương trình mà chúng có thể làm được gì cho họ.
- Xác định các nhiệm vụ cần thiết để thực hiện công việc, và những nhiệm vụ nào cần phải thực hiện trước khi có thể thực hiện được những nhiệm vụ đó.
Xác định [các] định dạng thích hợp cho tài liệu. Tài liệu phần mềm có thể được cấu trúc theo 1 trong 2 định dạng, tài liệu tham khảo và hướng dẫn sử dụng. Đôi khi, kết hợp các định dạng là cách tiếp cận tốt nhất.
- Định dạng hướng dẫn tham khảo được dành để giải thích các tính năng riêng lẻ của một ứng dụng phần mềm [nút, tab, trường và hộp thoại] và cách chúng hoạt động. Nhiều file trợ giúp được viết ở định dạng này, đặc biệt là trợ giúp theo ngữ cảnh hiển thị chủ đề có liên quan bất cứ khi nào người dùng nhấp vào nút Trợ giúp trên một màn hình cụ thể.
- Định dạng hướng dẫn sử dụng giải thích cách sử dụng phần mềm để thực hiện một tác vụ cụ thể. Hướng dẫn sử dụng thường được định dạng dưới dạng hướng dẫn in hoặc PDF, mặc dù một số file trợ giúp bao gồm các chủ đề về cách thực hiện các tác vụ cụ thể. [Các chủ đề trợ giúp này thường không nhạy cảm với ngữ cảnh, mặc dù chúng có thể được siêu liên kết đến từ các chủ đề đó].
Quyết định [các] dạng tài liệu sẽ có. Tài liệu phần mềm dành cho người dùng cuối có thể có 1 hoặc nhiều dạng: sách hướng dẫn in, tài liệu PDF, file trợ giúp hoặc trợ giúp trực tuyến. Mỗi biểu mẫu được thiết kế để chỉ cho người dùng cách sử dụng từng chức năng của chương trình, cho dù ở dạng hướng dẫn hay hướng dẫn; trong trường hợp file trợ giúp và trợ giúp trực tuyến, điều này có thể bao gồm video trình diễn cũng như văn bản và đồ họa tĩnh.
Các file trợ giúp và trợ giúp trực tuyến phải được lập chỉ mục và có thể tìm kiếm từ khóa để cho phép người dùng nhanh chóng tìm thấy thông tin họ đang tìm kiếm. Mặc dù các công cụ tạo file trợ giúp có thể tự động tạo chỉ mục, nhưng thường tốt hơn là tạo chỉ mục theo cách thủ công, sử dụng các thuật ngữ mà người dùng có thể tìm kiếm.
Chọn công cụ tài liệu thích hợp. Hướng dẫn sử dụng bản in hoặc PDF có thể được viết bằng chương trình xử lý văn bản như Word hoặc trình soạn thảo văn bản phức tạp như FrameMaker, tùy thuộc vào độ dài và độ phức tạp của chúng. File trợ giúp có thể được viết bằng công cụ tạo trợ giúp như RoboHelp, Help và Manual, Doc-To-Help, Flare, HelpLogix hoặc HelpServer.
Câu hỏi và câu trả lời của cộng đồng
Có bất kỳ công cụ miễn phí nào cho tài liệu phần mềm không? Hãy thử Doxygen để tạo ra các trang hướng dẫn dạng Web. Ngoài ra bạn có thể sử dụng LaTeX để xuất ra file PDF.
Tôi đã thấy các lần nhấn phím được ghi lại ở nhiều định dạng. Có một tiêu chuẩn thực tế cho các mặt hàng hay tất cả chúng đều khác nhau?
Không có tiêu chuẩn chung; tuy nhiên, bạn nên đặt tiêu chuẩn cho các tài liệu của riêng mình. Để có một vài ý tưởng, hãy xem Hướng dẫn tạo kiểu của Microsoft [có sẵn trên Amazon] và Hướng dẫn kiểu của Apple [//help.apple.com/applestyleguide]. Chúng có các phong cách khác nhau, vì vậy nếu bạn viết tài liệu đa nền tảng, bạn có thể sử dụng một số yếu tố từ hướng dẫn này và một số yếu tố từ hướng dẫn khác.