Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- HPX
- Người viết nội dung kỹ thuật:
- rstobaugh
- Tên dự án:
- Chỉnh sửa và đơn giản hoá tài liệu HPX hiện có
- Độ dài dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Đề xuất của tôi là chỉnh sửa và đơn giản hoá nội dung của tài liệu HPX hiện có. Đề xuất của tôi là một dự án theo thời hạn tiêu chuẩn (3 tháng) tập trung vào việc sửa đổi hai chương của hướng dẫn của nhóm STE||AR: ""Hệ thống xây dựng và khởi chạy HPX"" (1) và ""Định cấu hình ứng dụng HPX"" (2).
Chương ""Hệ thống xây dựng và khởi chạy HPX"" có một số lỗi ngữ pháp, cũng như chứa ngôn ngữ gây nhầm lẫn và cách viết hoa không nhất quán của các thuật ngữ như "CMake". Ngoài ra, chương này chứa thông tin lặp lại mà tôi dự định sắp xếp lại, hợp nhất và cắt bớt nếu cần. Mặc dù chương ""Định cấu hình ứng dụng HPX"" cũng chứa một vài lỗi ngữ pháp cần được khắc phục, nhưng mối lo ngại chính của tôi đối với chương này là tính dễ hiểu của nó đối với người dùng. Chương này có ba vấn đề thiết kế chính mà tôi dự định giải quyết:
Một số tiêu đề nằm trọn trong văn bản, gây khó khăn cho việc đọc lướt qua chương. Hiện tại, người dùng cần phải đọc kỹ tài liệu hướng dẫn để hiểu mục đích của từng bảng. Đây không phải là cách hầu hết người dùng tương tác với sách hướng dẫn, đặc biệt là nếu họ đã đọc qua nội dung trước đó. Thay vào đó, tôi dự định đảm bảo mỗi bảng đều có tiêu đề rõ ràng, dễ thấy để người dùng có thể dễ dàng xem nếu cuộn qua văn bản.
Khi liệt kê nhiều thuộc tính trong một tiêu đề cụ thể, các thuộc tính không tuân theo thứ tự hợp lý. Mặc dù các tài sản được nhóm lại với nhau theo một chủ đề chung, nhưng không có nhóm phụ nào, khiến thông tin có vẻ rời rạc. Ví dụ: người dùng có thể gặp một số thuộc tính liên quan đến vị trí, một số thuộc tính liên quan đến chủ đề khác, sau đó là một thuộc tính khác liên quan đến vị trí. Việc thiếu cấu trúc nội bộ trong tiêu đề khiến bạn khó tìm thấy tất cả thông tin về một chủ đề phụ cụ thể. Do đó, tôi dự định sắp xếp lại một số biểu đồ để nhóm các thông tin tương tự với nhau theo từng tiêu đề một cách rõ ràng hơn.
Người dùng buộc phải di chuyển qua lại giữa các phần (hoặc mở hướng dẫn trong hai thẻ riêng biệt) để hiểu đầy đủ một số hướng dẫn nhất định. Có những điểm mà chương đưa người dùng đến một câu duy nhất trong phần trước theo cách buộc người đọc phải cuộn lên hoặc đi theo một siêu liên kết để hiểu chính xác chỉ dẫn, vì tài liệu hướng dẫn sử dụng ngôn từ mơ hồ như "bước này được tạo sau bước 11" trong phần trước. Mặc dù phương thức này giúp loại bỏ việc lặp lại, nhưng lại khiến bạn khó hiểu hướng dẫn hơn vì đây là những nhiệm vụ cần được thực hiện theo thứ tự cụ thể. Thay vào đó, tôi đề xuất sử dụng từ ngữ cụ thể hơn để người dùng không phải gián đoạn quá trình đọc bằng cách chuyển đổi giữa các phần hoặc tài liệu.
Nếu hoàn thành các phần này trước khi tiến trình chuẩn kết thúc, tôi cũng muốn dọn dẹp trang "Tại sao nên dùng HPX?" (3) trong Tài liệu người dùng của nhóm STE||AR. Trang này chứa nội dung giới thiệu lặp đi lặp lại mà tôi hy vọng có thể hợp nhất và chứa nội dung không nhất quán về cách viết hoa (đặc biệt là các thuật ngữ) và giọng điệu, khiến trang này có cảm giác không thống nhất. Mục tiêu của tôi là tạo ra một phần giới thiệu nhất quán và thống nhất hơn về công việc của nhóm STE||AR.