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