Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- SciPy
- Người viết nội dung kỹ thuật:
- mkg33
- Tên dự án:
- Tài liệu hướng đến người dùng và việc tái cấu trúc kỹ lưỡng
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Động lực:
Tôi dự định tái cấu trúc tài liệu hiện có để người dùng có nhu cầu khác có thể dễ dàng truy cập tài liệu đó. Rõ ràng là nhà nghiên cứu rất có thể sẽ quan tâm đến các tính năng nâng cao và tinh tế, trong khi những người dùng không có chuyên môn trước đó lại đánh giá cao hướng dẫn và sơ đồ từng bước.
Tôi quan tâm đến việc theo đuổi dự án này vì lý do cá nhân và nghề nghiệp: trước tiên, tôi muốn đóng góp đáng kể cho SciPy vì nghiên cứu của riêng tôi đã hưởng lợi rất nhiều từ nó và thứ hai, tôi thường xuyên gặp không đủ (hoặc thiếu) tài liệu trong phần mềm khác và luôn tự hỏi người dùng có thể học cách sử dụng mã nhanh hơn bao nhiêu nếu họ được hướng dẫn chi tiết.
Mục tiêu:
Tôi muốn cải thiện tài liệu SciPy hiện có về cả nội dung và hình ảnh. Điểm quan trọng nhất trong cách tiếp cận của tôi đối với vấn đề này là việc triển khai và phân tích bản khảo sát người dùng, tức là một bản khảo sát ngắn gọn được thực hiện trực tuyến, cho phép nhiều người dùng nêu ra nhu cầu của họ liên quan đến tài liệu này. Tôi thực sự tin rằng ý kiến của họ nên là nguồn cảm hứng (làm cách nào khác để chúng tôi tạo ra một tài liệu thân thiện với người dùng hơn?).
Liên quan đến việc thực hiện dự án, giai đoạn đầu tiên sẽ bao gồm việc thiết kế và phân tích bài khảo sát người dùng, cũng như giải quyết một số vấn đề về kiểu cách mà tôi nhận thấy trong tài liệu hiện tại. Ví dụ: thiếu tính nhất quán (ví dụ: mảng 2 chiều xuất hiện cùng với mảng hai chiều), các câu tích hợp cần được viết lại hoặc thiếu thứ tự bảng chữ cái trong một số trang con. Giai đoạn thứ hai sẽ tập trung vào việc giới thiệu các hướng dẫn bằng hình ảnh chứa siêu liên kết đến các chủ đề có liên quan (dựa trên kết quả khảo sát và các yêu cầu cộng đồng khác). Về lâu dài, tôi muốn đạt được một tài liệu chất lượng cao phù hợp với nhiều kiểu người dùng. Hơn nữa, tôi sẽ cố gắng làm cho các hướng dẫn này nhất quán hơn cả về mặt ngôn ngữ lẫn cấu trúc. Cuối cùng nhưng không kém phần quan trọng, tôi muốn viết hướng dẫn mới (dựa trên nhu cầu hiện tại của cộng đồng).
Khảo sát người dùng:
Tôi đề xuất sử dụng Google Biểu mẫu vì một số lý do liên quan đến bài khảo sát người dùng. Trước hết, Google Biểu mẫu là miễn phí và cung cấp chức năng không giới hạn (về số lượng người trả lời, câu hỏi, v.v.), có hình thức trực quan hấp dẫn, các tùy chọn khảo sát hữu ích nhất (ví dụ: thang đo tuyến tính tùy chỉnh, hộp đánh dấu và câu hỏi trắc nghiệm) và quan trọng nhất là có thể dễ dàng xuất kết quả để phân tích thống kê. Dựa trên kết quả nghiên cứu trực tuyến, có vẻ như hiện tại Google Biểu mẫu là công cụ miễn phí tốt nhất để thực hiện khảo sát. Một lưu ý ít nghiêm trọng hơn, đó sẽ là một cử chỉ tốt nếu sử dụng sản phẩm của Google trong một sáng kiến do Google thực hiện.
Tôi đã tạo một bản khảo sát sơ bộ với các câu hỏi mẫu (bạn có thể truy cập vào bản khảo sát này tại https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Số lượng câu hỏi hợp lý trong phiên bản cuối cùng nên nằm trong khoảng từ 10 đến 15. Để có được kết quả cụ thể, tôi khuyên bạn nên chủ yếu sử dụng câu hỏi trắc nghiệm, thang điểm tuyến tính và một vài hộp đánh dấu. Tuy nhiên, thang đo tuyến tính không được giống với phổ đầy đủ (điều này chỉ gây nhầm lẫn và kết quả có thể gây ra độ phân tán cao). Chỉ nên dùng tối đa hai câu hỏi mở, nếu không, các kết quả sẽ có sự phân tán xa và không hữu ích chút nào. Tôi cho rằng ngay cả số lượng câu trả lời rất lớn cũng không phải là vấn đề vì trên thực tế, dữ liệu có thể dễ dàng được xuất và phân tích tự động bằng phần mềm thống kê. Giả sử số lượng câu trả lời thực sự rất cao, thì việc phân tích các câu hỏi mở có thể tốn chút thời gian, nhưng tôi cho rằng sẽ không quá nhiều. Suy cho cùng thì một người dùng thông thường sẽ không có khả năng viết bài luận về tình trạng của tài liệu. Trong trường hợp xấu nhất, một số câu trả lời có thể chỉ được lưu trữ để phân tích trong tương lai.
Hướng dẫn đồ hoạ:
Tầm nhìn của tôi về hướng dẫn dạng đồ hoạ (nhằm dùng làm công cụ điều hướng) dựa trên một tiền đề phổ biến rằng (hầu hết) con người có khả năng xử lý các cấu trúc trực quan đơn giản hơn là thông tin thuần tuý dựa trên văn bản. Hơn nữa, một sơ đồ định hướng theo chủ đề với các đường kết nối các chủ đề tương tự nhau về mối quan tâm chắc chắn là một tài sản có giá trị cao đối với người dùng ít kinh nghiệm (và không chỉ).
Liên quan đến thông tin triển khai, tôi đề xuất sử dụng gói TikZ. Trước tiên, đây là một công cụ mạnh mẽ và có vẻ như không có nguy cơ sắp bị ngừng sử dụng. Công cụ này cũng cung cấp đầu ra chất lượng cao, có tài liệu thực sự vững chắc và là chủ đề thường xuyên trên TeX StackExchange cũng như các diễn đàn chính thống khác. Quan trọng nhất, việc tích hợp tệp TikZ (chính xác hơn là rất nhiều siêu liên kết trong đó) với tài liệu HTML dường như không gây ra vấn đề lớn do sự tồn tại của nhiều gói và bản sửa lỗi để nhúng ảnh TikZ trong HTML (ví dụ: TeX4ht).
Bạn có thể dễ dàng giải quyết vấn đề về việc bảo trì các hướng dẫn trong SciPy trong tương lai bằng cách sử dụng Overleaf (hỗ trợ cộng tác và cung cấp bản xem trước tức thì) và các mẫu được xác định trước mà tôi sẽ cung cấp. Về cơ bản, các hướng dẫn đồ họa có thể không quá khác biệt với nhau. Cấu trúc, bảng màu và hình dạng ít nhiều sẽ là bất biến, do đó việc định hình lại và tuỳ chỉnh thêm sẽ không thành vấn đề.
(Vui lòng xem phiên bản đầy đủ của đề xuất này – có trong thư mục GSoD dùng chung.)