Tài liệu phần mềm tốt, cho dù đó là tài liệu đặc tả cho người lập trình và kiểm thử, tài liệu kỹ thuật cho người dùng nội bộ, hoặc hướng dẫn sử dụng và tệp trợ giúp cho người dùng cuối, sẽ giúp người dùng hiểu được các tính năng và chức năng của phần mềm. Tài liệu tốt là tài liệu cụ thể, rõ ràng và có liên quan, với tất cả thông tin mà người dùng cần. Bài viết này sẽ hướng dẫn bạn viết tài liệu phần mềm cho người dùng kỹ thuật và người dùng cuối.
Bươc chân
Phương pháp 1/2: Viết tài liệu phần mềm cho người dùng kỹ thuật
Bước 1. Biết những thông tin cần bao gồm
Tài liệu đặc tả này được sử dụng làm sổ tay tham khảo cho các nhà thiết kế giao diện, lập trình viên viết mã và người kiểm tra xác minh hiệu suất phần mềm. Thông tin cần được đưa vào sẽ tùy thuộc vào chương trình được tạo, nhưng có thể bao gồm những điều sau:
- Các tệp quan trọng trong ứng dụng, chẳng hạn như tệp do nhóm phát triển tạo, cơ sở dữ liệu được truy cập khi chương trình đang chạy và các ứng dụng của bên thứ ba.
- Hàm và chương trình con, bao gồm giải thích về việc sử dụng hàm / chương trình con, các giá trị đầu vào và đầu ra.
- Các biến và hằng số của chương trình và cách chúng được sử dụng.
- Cấu trúc chương trình tổng thể. Đối với các chương trình dựa trên ổ đĩa, bạn có thể cần mô tả từng mô-đun và thư viện. Hoặc, nếu bạn đang viết hướng dẫn sử dụng cho một chương trình dựa trên web, bạn có thể cần giải thích mỗi trang sử dụng tệp nào.
Bước 2. Quyết định mức độ tài liệu nào nên có và có thể tách rời khỏi mã chương trình
Càng có nhiều tài liệu kỹ thuật được bao gồm trong mã chương trình, thì càng dễ dàng cập nhật và bảo trì nó, cũng như giải thích các phiên bản khác nhau của chương trình. Tối thiểu, tài liệu trong mã chương trình phải bao gồm việc sử dụng các hàm, chương trình con, biến và hằng số.
- Nếu mã nguồn của bạn dài, bạn có thể viết tài liệu vào tệp trợ giúp, tệp này sau đó có thể được lập chỉ mục hoặc tìm kiếm bằng các từ khóa nhất định. Các tệp tài liệu riêng biệt rất hữu ích nếu logic chương trình được chia thành nhiều trang và bao gồm các tệp hỗ trợ, chẳng hạn như ứng dụng web.
- Một số ngôn ngữ lập trình (chẳng hạn như Java, Visual Basic. NET hoặc C #) có các tiêu chuẩn tài liệu mã riêng. Trong những trường hợp như vậy, hãy tuân theo tài liệu tiêu chuẩn phải có trong mã nguồn.
Bước 3. Chọn công cụ tài liệu thích hợp
Trong một số trường hợp, công cụ tài liệu được xác định bởi ngôn ngữ lập trình được sử dụng. Các ngôn ngữ C ++, C #, Visual Basic, Java, PHP và các ngôn ngữ khác có các công cụ tài liệu riêng. Tuy nhiên, nếu không, các công cụ được sử dụng sẽ phụ thuộc vào tài liệu yêu cầu.
- Một trình xử lý văn bản như Microsoft Word thích hợp để tạo các tệp văn bản tài liệu, miễn là tài liệu ngắn gọn và đơn giản. Để tạo tài liệu dài với văn bản phức tạp, hầu hết người viết kỹ thuật chọn một công cụ tài liệu chuyên biệt, chẳng hạn như Adobe FrameMaker.
- Các tệp trợ giúp để ghi lại mã nguồn có thể được tạo bằng chương trình tạo tệp hỗ trợ, chẳng hạn như RoboHelp, Help và Manual, Doc-To-Help, MadCap Flare hoặc HelpLogix.
Phương pháp 2/2: Viết tài liệu phần mềm cho người dùng cuối
Bước 1. Biết các lý do kinh doanh cơ bản của việc tạo sổ tay hướng dẫn
Trong khi lý do chính của tài liệu phần mềm là để giúp người dùng hiểu cách sử dụng ứng dụng, có một số lý do khác có thể làm cơ sở cho việc tạo tài liệu, chẳng hạn như giúp bộ phận tiếp thị bán ứng dụng, cải thiện hình ảnh của công ty và giảm hỗ trợ kỹ thuật chi phí. Trong một số trường hợp, tài liệu được yêu cầu để tuân thủ các quy định hoặc các yêu cầu pháp lý khác.
Tuy nhiên, tài liệu không phải là một sự thay thế tốt cho một giao diện. Nếu một ứng dụng yêu cầu nhiều tài liệu để vận hành, thì nó nên được thiết kế để trực quan hơn
Bước 2. Biết đối tượng mục tiêu của tài liệu
Nói chung, người dùng phần mềm có kiến thức máy tính hạn chế ngoài các ứng dụng mà họ sử dụng. Có một số cách để đáp ứng nhu cầu tài liệu của họ:
- Chú ý đến chức danh của người sử dụng phần mềm. Ví dụ, quản trị viên hệ thống thường hiểu các ứng dụng máy tính khác nhau, trong khi thư ký chỉ biết các ứng dụng mà anh ta sử dụng để nhập dữ liệu.
- Chú ý đến người dùng phần mềm. Mặc dù các vị trí của họ nhìn chung tương thích với các nhiệm vụ được thực hiện, các vị trí này có thể có khối lượng công việc khác nhau, tùy thuộc vào địa điểm kinh doanh. Bằng cách phỏng vấn những người dùng tiềm năng, bạn có thể tìm hiểu xem đánh giá của bạn về chức danh công việc của họ có chính xác hay không.
- Chú ý đến tài liệu hiện có. Tài liệu về chức năng phần mềm và thông số kỹ thuật có thể hiển thị những gì người dùng cần biết để sử dụng chúng. Tuy nhiên, hãy nhớ rằng người dùng có thể không quan tâm đến việc biết "nội dung" của chương trình.
- Biết những gì cần thiết để hoàn thành một nhiệm vụ và những gì cần thiết trước khi bạn có thể hoàn thành nó.
Bước 3. Xác định định dạng thích hợp cho tài liệu
Tài liệu phần mềm có thể được sắp xếp theo 1 hoặc 2 định dạng, cụ thể là sách tham khảo và sách hướng dẫn. Đôi khi, kết hợp hai định dạng là một giải pháp tốt.
- Các định dạng tham chiếu được sử dụng để mô tả tất cả các tính năng của phần mềm, chẳng hạn như các nút, tab, trường và hộp thoại cũng như cách chúng hoạt động. Một số tệp trợ giúp được viết ở định dạng này, đặc biệt là những tệp phân biệt ngữ cảnh. Khi người dùng nhấp vào Trợ giúp trong một màn hình nhất định, người dùng sẽ nhận được chủ đề liên quan.
- Định dạng thủ công được sử dụng để giải thích cách thực hiện điều gì đó với phần mềm. Sách hướng dẫn thường ở định dạng in hoặc PDF, mặc dù một số trang trợ giúp cũng bao gồm hướng dẫn về cách thực hiện một số việc nhất định. (Nói chung, các định dạng thủ công không nhạy cảm với ngữ cảnh, nhưng có thể được liên kết từ các chủ đề nhạy cảm với ngữ cảnh). Sổ tay thường ở dạng hướng dẫn, với phần tóm tắt các công việc cần thực hiện dưới dạng mô tả và hướng dẫn được định dạng theo các bước.
Bước 4. Quyết định loại tài liệu
Tài liệu phần mềm cho người dùng có thể được đóng gói ở một hoặc nhiều định dạng sau: sách hướng dẫn in, tệp PDF, tệp trợ giúp hoặc trợ giúp trực tuyến. Mỗi loại tài liệu được thiết kế để chỉ cho bạn cách sử dụng các chức năng của phần mềm, cho dù đó là tài liệu hướng dẫn hay hướng dẫn. Các trang trợ giúp và tài liệu trực tuyến cũng có thể bao gồm video trình diễn, văn bản và hình ảnh tĩnh.
Các tệp trợ giúp và hỗ trợ trực tuyến nên được lập chỉ mục và có thể tìm kiếm bằng từ khóa để người dùng có thể nhanh chóng tìm thấy thông tin họ cần. Mặc dù ứng dụng tạo tệp trợ giúp có thể tự động tạo chỉ mục, bạn vẫn nên tạo chỉ mục theo cách thủ công bằng cách sử dụng các từ khóa thường được tìm kiếm
Bước 5. Chọn công cụ tài liệu thích hợp
Sách hướng dẫn in hoặc PDF có thể được tạo 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 nâng cao như FrameMaker, tùy thuộc vào độ dài và độ phức tạp của tệp. Các tệp trợ giúp có thể được viết bằng chương trình tạo tệp trợ giúp, chẳng hạn như RoboHelp, Help và Manual, Doc-To-Help, Flare, HelpLogix hoặc HelpServer.
Lời khuyên
- Văn bản của tài liệu chương trình phải được cấu trúc sao cho dễ đọc. Đặt hình ảnh càng gần văn bản thích hợp càng tốt. Chia nhỏ tài liệu theo các phần và chủ đề một cách hợp lý. Mỗi phần hoặc chủ đề nên mô tả một vấn đề cụ thể, cả nhiệm vụ và các tính năng của chương trình. Các vấn đề liên quan có thể được giải thích bằng các liên kết hoặc danh sách tham khảo.
- Mỗi công cụ tài liệu được mô tả trong bài viết này có thể được bổ sung bởi một chương trình tạo ảnh chụp màn hình, chẳng hạn như SnagIt nếu tài liệu của bạn yêu cầu nhiều ảnh chụp màn hình. Giống như bất kỳ tài liệu nào khác, bạn cũng nên bao gồm ảnh chụp màn hình để giúp giải thích cách ứng dụng hoạt động, thay vì "dụ" người dùng.
- Chú ý đến phong cách là rất quan trọng, đặc biệt nếu bạn đang viết tài liệu phần mềm cho người dùng cuối. Địa chỉ người dùng bằng đại từ "bạn", thay vì "người dùng".
