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ở:
- NumPy
- Người viết nội dung kỹ thuật:
- cooperrc
- Tên dự án:
- Tài liệu NumPy để giáo dục cộng đồng
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Giới thiệu
NumPy cung cấp tính năng điện toán dựa trên mảng nhanh chóng và rõ ràng trong một thư viện phần mềm nguồn mở miễn phí. Đây là một gói cơ bản trong ngăn xếp SciPy để tính toán khoa học [1]. Hơn 370 nghìn dự án sử dụng để tính toán mảng hiệu quả [2]. Người dùng NumPy sẽ được chào đón bằng một trang web mới có các ứng dụng và nghiên cứu điển hình [1]. Khi tìm thấy trang tài liệu, người dùng mới sẽ thấy nhiều đường liên kết "Bắt đầu tại đây" và các hướng dẫn nhập môn có thể gây choáng ngợp cho người mới bắt đầu, chẳng hạn như Kiến thức cơ bản về NumPy/hoán đổi byte. Tôi bắt đầu sử dụng NumPy 10 năm trước khi học cao học. Tôi đã phải ghép nối các bài đăng trên blog, ghi chú bài giảng và câu trả lời trên StackExchange để tránh phải xem tài liệu NumPy. Hiện có hơn 360 nghìn cuộc trò chuyện trên StackExchange liên quan đến NumPy. Tôi cho rằng những người dùng khác cũng đã đạt được thành công trong NumPy. Các thành phần tạo nên công cụ giáo dục là giao tiếp và cộng đồng [4]. Tài liệu cần thiết lập một cộng đồng phản ánh các mục tiêu mong muốn của dự án. Tài liệu phải nhất quán và là hướng dẫn rõ ràng cho người dùng mới. Hướng dẫn phải cung cấp cho người dùng mới các bước dễ làm theo và giúp họ cảm thấy thoải mái khi sử dụng thư viện [3]. Tài liệu này sẽ chào đón người dùng mới tham gia cộng đồng NumPy. Cấu trúc, tốc độ và tác giả của tài liệu đều cần tạo ra một nơi chào đón việc khám phá và giao tiếp. Đề xuất này sẽ sắp xếp và bổ sung những phần còn thiếu trong tài liệu NumPy hiện tại để người dùng mới được hướng dẫn và chào đón vào cộng đồng.
Kiến thức mà người dùng truyền đạt được thu thập thông qua quá trình kiểm thử và thử nghiệm [4,5]. Kiến thức phụ thuộc vào phương thức kiểm thử và đánh giá. Nội dung cung cấp các mục tiêu và ứng dụng rõ ràng trong hướng dẫn giúp người dùng thử nghiệm và đánh giá các ý tưởng và phương pháp mới. Cộng đồng có thể xây dựng cơ sở kiến thức giúp nâng cao kỹ năng, dữ kiện và ứng dụng. Không gian hướng dẫn mang lại lợi ích hai chiều. Trước tiên, người dùng mới và người dùng có kinh nghiệm đều có một bộ mục tiêu rõ ràng để thử nghiệm và xây dựng thử nghiệm. Thứ hai, những người có thể đóng góp tài liệu có không gian để trao đổi về mục tiêu, phương pháp và giải pháp của họ. Không gian hướng dẫn này đáp ứng nhu cầu cấp thiết là giúp tài liệu của NumPy dễ tiếp cận hơn đối với người dùng mới và những người có thể đóng góp. Kiến thức hiện tại
John Dewey cho rằng nền tảng của việc học là trải nghiệm thực sự [4]. Cộng đồng NumPy có rất nhiều kinh nghiệm thực tế có thể chia sẻ với người dùng khác. Hoạt động giáo dục được xây dựng dựa trên cộng đồng và sự giao tiếp. Trang tài liệu được sắp xếp có tổ chức giúp người dùng mới trải nghiệm NumPy. Công cụ này cũng tạo một mẫu có cấu trúc để những người đóng góp tiềm năng có thể chia sẻ kinh nghiệm trong NumPy.
Có bốn không gian được nhóm rộng cho tài liệu về phần mềm [3]: không gian hướng dẫn, không gian hướng dẫn, không gian giải thích và không gian tham khảo. Tài liệu NumPy có một số tài liệu trong phần hướng dẫn kết hợp nội dung giải thích và nội dung hướng dẫn cách đưa vào phần hướng dẫn. Không gian hướng dẫn phải tập trung vào việc giáo dục người dùng và sử dụng các bước dễ lặp lại để truyền đạt ý tưởng. Không gian hướng dẫn cung cấp nhiều quy trình hướng mục tiêu hơn mà người dùng có thể áp dụng trong các ứng dụng thực tế. Không gian giải thích cung cấp thông tin chi tiết về chuỗi tài liệu trong mỗi hàm. Phần hướng dẫn và phần hướng dẫn cách làm hiện tại không được phân định rõ ràng và đôi khi đi vào phần giải thích và phần tham khảo. Có một hướng dẫn rất hay dành cho người mới bắt đầu tuyệt đối. Người dùng Matlab có thể tham khảo tài liệu tham khảo hữu ích để xây dựng mã NumPy trong phần "Numpy dành cho người dùng Matlab". Việc mô tả rõ 4 khoảng trống này giúp tài liệu rõ ràng hơn.
Khoảng trống trong cơ sở kiến thức/Nhu cầu chưa được đáp ứng
Tài liệu hiện tại đề cập đến nhiều chủ đề cần thiết, nhưng thiếu sự phân biệt rõ ràng giữa phần hướng dẫn, cách làm, nội dung giải thích và không gian tham khảo. Điều này gây nhầm lẫn cho những người đóng góp tiềm năng. Người dùng mới có thể bị choáng ngợp bởi nội dung giải thích và tài liệu tham khảo trong phần hướng dẫn, còn những người có thể đóng góp lại gặp phải rào cản để đóng góp. Tôi đề xuất một bố cục dễ tiếp cận hơn cho người mới và những người có thể đóng góp tài liệu với quy trình hợp lý trong tài liệu và quản lý các yêu cầu kéo cho tài liệu hướng dẫn do người dùng đóng góp. Mục tiêu dài hạn của tôi là xây dựng cộng đồng tài liệu để việc học qua tài liệu là một trải nghiệm vừa học hỏi, vừa giao tiếp. Mô hình soạn tài liệu này sẽ giúp giáo dục dựa trên trải nghiệm thực tế cho người mới tham gia và người đóng góp tiềm năng.
Lý do
Đề xuất này cho Google Summer of Docs rất quan trọng đối với các mục tiêu nghề nghiệp và mục tiêu sư phạm của tôi. Tôi sử dụng NumPy và SciPy trong tất cả các khoá học của mình. Học viên của tôi khó sử dụng tài liệu hiện tại. Tôi muốn sử dụng kinh nghiệm của mình trong việc hướng dẫn những người không học ngành Khoa học máy tính cách lập trình để giúp sắp xếp, chỉnh sửa và lấp đầy những khoảng trống trong các hướng dẫn hiện tại. Sau đó, tôi có thể sử dụng tài liệu này làm sách giáo khoa và tài liệu tham khảo cho các khoá học của mình. Tôi đã tạo hàng chục hướng dẫn, bài tập và ví dụ bằng Python và
Mục tiêu cụ thể
Tôi có 3 mục tiêu cụ thể cho đề xuất của Google Summer of Tài liệu: 1. Sắp xếp tài liệu hiện tại, 2. Chỉnh sửa các hướng dẫn hiện tại (Hướng dẫn cho người mới bắt đầu, Tạo mảng, Lập chỉ mục, Đại số tuyến tính và NumPy cho Matlab) để di chuyển thông tin tham khảo vào Không gian giải thích và 3. Xây dựng tài liệu hướng dẫn cùng học viên. Mỗi mục tiêu cụ thể đều có một kết quả dự kiến cho đề xuất.
Ba mục đích cụ thể này nhằm giúp tài liệu trở nên thân thiện hơn với người dùng mới và xây dựng cấu trúc cho những người đóng góp tiềm năng. Các mục tiêu này cũng giúp thúc đẩy mục tiêu dài hạn là tiếp tục phát triển cộng đồng tài liệu NumPy. Kết quả dự kiến
Tôi có 3 kết quả dự kiến như sau: 1. Một trang web tài liệu đã sửa đổi tách biệt rõ ràng bốn không gian: hướng dẫn, cách làm, giải thích và tham khảo, 2. hướng dẫn mới cho: đọc và viết mảng, tạo mảng (np.zeros, np.ones, np.block, v.v.) và phép toán đại số tuyến tính và phần tử trong NumPy và 3. một không gian hướng dẫn được sắp xếp.
Những kết quả dự kiến này sẽ giúp người dùng mới tiến bộ qua các tài liệu, cung cấp cho những người đóng góp tài liệu tiềm năng các kiểu và định dạng rõ ràng, giúp các hướng dẫn hiện tại ngắn gọn và dễ theo dõi hơn, chuyển phần giải thích sang một phần riêng biệt và những người đóng góp tài liệu mới sẽ có thể đóng góp các trường hợp sử dụng nhỏ vào phần hướng dẫn mà không cần tạo toàn bộ tài liệu Sphinx. Chúng tôi muốn tiếp tục xây dựng cộng đồng dạy và học.
Những người đóng góp tài liệu mới có thể đóng góp các trường hợp sử dụng nhỏ cho hàng triệu người dùng mà không cần tạo toàn bộ tài liệu Sphinx. Chúng tôi muốn tiếp tục xây dựng cộng đồng dạy và học. Tài liệu đề xuất này sẽ mô phỏng tài liệu nguồn mở hiện tại như Matplotlib, Divio, v.v. Người dùng mới và những người đóng góp tiềm năng sẽ dễ dàng tìm hiểu cách áp dụng NumPy trong các lĩnh vực và phần mềm của họ.
Tiến trình của dự án là từ ngày 14/9 đến ngày 30/11. Bước đầu tiên là tạo tài liệu và tách nội dung trong các hướng dẫn hiện tại thành nội dung Hướng dẫn, Cách thực hiện và Giải thích. Việc này sẽ được thực hiện trong 5 tuần đầu tiên của dự án, thuộc Kết quả 1 và 2 – lần lượt sửa đổi trang web và hướng dẫn. Cách sắp xếp Tài liệu đề xuất được thể hiện trong Tài liệu đề xuất bên dưới.
Tài liệu đề xuất:
i.Tutorials:
- Kiến thức cơ bản tuyệt đối dành cho người mới bắt đầu (xoá quá trình cài đặt, có thể thay thế pandas nhập/xuất bằng numpy.loadtxt không?)
- đường liên kết đến bài viết "numpy là gì"
- đường liên kết đến hướng dẫn cài đặt cơ bản tại đây
- Hướng dẫn bắt đầu nhanh (dành cho những người đã tham khảo hướng dẫn về Python)
- Cách dùng mảng NumPy
- tạo mảng (np.zeros, np.ones, np.block, v.v.) (viết: mức độ ưu tiên trung bình-thấp)
- phép toán theo phần tử (+,-,*,/) và phép toán đại số tuyến tính (+,-,@, linalg.solve) (write:med priority)
- Đọc và ghi dữ liệu bằng Numpy (ghi: mức độ ưu tiên cao)
- Lập chỉ mục
ii. Hướng dẫn:
- Đại số tuyến tính trên mảng n chiều (muốn chỉnh sửa tiêu đề và nội dung mô tả, có thể thay đổi tiêu đề thành "Xử lý hình ảnh bằng đại số tuyến tính của Numpy")
- liên kết đến nội dung hướng dẫn chi tiết (công việc đang diễn ra)
iii. Giải thích:
- Loại dữ liệu
- I/O bằng Numpy
- Lập chỉ mục
- Phát sóng
- Hoán đổi byte
- Mảng có cấu trúc
- Viết vùng chứa mảng tuỳ chỉnh
- tạo lớp con ndarray
- Khác
iv. Không gian tham chiếu:
- Bảng thuật ngữ
- Tài liệu tham khảo Numpy API
- Numpy dành cho người dùng Matlab (bảng tương đương là một bảng tham khảo tuyệt vời, nhưng phần thảo luận về mảng/ma trận lại gây mất tập trung và có vẻ như không còn được dùng nữa)
Sau khi hoàn thành Google Season of Docs, tôi đề xuất những kết quả sau:
- Trang web tài liệu được sửa đổi phân tách rõ ràng bốn không gian: Hướng dẫn, Hướng dẫn, Giải thích và Tham khảo
- Hướng dẫn mới về: tạo mảng (np.zeros, np.ones, np.block, v.v.), các phép toán theo phần tử (+,-,*,/) và các phép toán đại số tuyến tính (+,-,@, linalg.solve) và Đọc và ghi dữ liệu bằng Numpy (ưu tiên cao)
- Tư vấn hướng dẫn cách đóng góp nhiều hơn cho người dùng và góp phần thực hiện mục tiêu của cộng đồng trong việc giảng dạy và học tập
Mỗi kết quả có một số bước được nêu trong bảng dưới đây cho Kết quả 1-3. Trong khi Tài liệu đề xuất được gửi đi xem xét, bạn sẽ viết hướng dẫn "Đọc/ghi mảng" có mức độ ưu tiên cao để gửi dưới dạng yêu cầu kéo trong Kết quả 2. Trong quá trình xem xét trang web đã sửa đổi và hướng dẫn "Đọc/Ghi mảng" đã cập nhật, tôi sẽ bắt đầu viết hướng dẫn tạo mảng bằng các hàm NumPy, ví dụ: np.ones, np.zeros, np.diag. Thời gian còn lại sẽ được dùng để phản hồi các vấn đề về yêu cầu kéo và bắt đầu viết hướng dẫn về thứ hạng 3: Các phép toán tử đại số tuyến tính và theo phần tử trong Python.
Kết quả thứ ba là tư vấn cho sinh viên tại Đại học Connecticut về việc xây dựng tài liệu trong kho lưu trữ numpy-tutorials. Tài liệu hướng dẫn hoặc hướng dẫn cách thực hiện mà bạn gửi sẽ là sổ ghi chú Jupyter sử dụng NumPy để giải quyết các vấn đề kỹ thuật. Tôi sẽ sử dụng một số ghi chú/ví dụ trong khoá học để gửi một sổ tay mẫu. Tôi sẽ khuyên học sinh tuân theo bố cục và cấu trúc trong quá trình chúng ta xây dựng mẫu và sơ đồ đóng khung. Kết quả này mang đến một trải nghiệm chân thực để học sinh truyền đạt các khái niệm và giải pháp cho nhiều đối tượng hơn. Đây là một cơ hội tuyệt vời để học viên tham gia và học hỏi cộng đồng NumPy.
Kết quả 1: Sửa đổi trang web Ngày giao hàng Kho lưu trữ nhánh và Tài liệu bản dựng bằng Sphinx 9/21 Tạo trang web với 4 không gian được xác định và liên kết 10/1 Di chuyển các hướng dẫn hiện tại vào các không gian thích hợp và Xây dựng tài liệu 10/10 Gửi PR đến github với các thay đổi đề xuất 11/1 Phản hồi nhận xét/đề xuất và sửa đổi PR đang diễn ra với Kết quả 2 Trang web đã sửa đổi 11/30
Kết quả 2: Sửa đổi hướng dẫn Ngày giao sản phẩm Xem lại thứ hạng sửa đổi hướng dẫn 9/21 Phân tách nội dung hướng dẫn hiện tại thành không gian Hướng dẫn và Giải thích 10/1 Viết thứ hạng 1: Đọc/Ghi mảng 10/10 Gửi PR đến github để phân tách và sửa đổi 10/20 Viết thứ hạng 2: PR tạo mảng 11/15 Viết thứ hạng 3: PR về các phép toán tử theo phần tử và đại số tuyến tính 11/30
Thứ hạng đề xuất của các bản sửa đổi hướng dẫn (có thể thay đổi theo ý kiến của người cố vấn/cộng đồng):
Đọc/Ghi các mảng hiện đang trống
Tạo mảng (np.zeros, np.ones, np.block, v.v.) Không tồn tại: sẽ giúp người dùng mới được giải thích và minh hoạ các công cụ tạo/tương tác với mảng phổ biến
Các phép toán đại số tuyến tính và phần tử (+,-,*,/ và +,-@,linalg.solve) Không tồn tại: điều này đặc biệt hữu ích cho 1. Người dùng Matlab và 2. Mọi người sử dụng cho đại số tuyến tính (học máy, hồi quy tuyến tính, v.v.)
Kết quả 3: Không gian hướng dẫn được tuyển chọn Ngày giao sản phẩm Đường liên kết ngoài(vấn đề/ví dụ)
Tạo ví dụ về hướng dẫn (đề xuất: Cách tìm tần số tự nhiên của dây guitar 10/20
Tạo mẫu hướng dẫn cho cộng tác viên mới 10/1 đang tiến hành Giới thiệu mẫu hướng dẫn và định hình nội dung đóng góp có thể có
Phối hợp với các cộng tác viên khác để xây dựng sổ tay hướng dẫn tuyển dụng sinh viên UConn và các thành viên khác trong cộng đồng Trạng thái ngày 7/1: đã phê duyệt chương trình học việc và nhận được đơn đăng ký
Mức ý nghĩa dự kiến
Đề xuất Mùa hè tài liệu này của Google sẽ tạo tài liệu NumPy , điền các hướng dẫn còn thiếu từ trang web và có được người đóng góp tài liệu. Là một Giáo sư về Kỹ thuật cơ khí, tôi dự định phân đoạn tài liệu để học viên có thể dễ dàng tìm thấy các hướng dẫn nhập môn và hướng dẫn thực hành. Tài liệu được phân đoạn: hướng dẫn, cách làm, tài liệu tham khảo và giải thích sẽ cung cấp cho những người đóng góp tiềm năng các ví dụ có cấu trúc để xây dựng tài nguyên mới. Tài liệu đề xuất này mang đến một trải nghiệm "cho và nhận" thông qua việc hướng dẫn và giao tiếp cho người dùng mới và người dùng có kinh nghiệm. Tài liệu hướng dẫn cách làm được đề xuất với các sinh viên của Đại học Connecticut sẽ đưa ý tưởng giáo dục và giao tiếp này vào thực tiễn. Chúng tôi muốn tất cả người dùng đều có thể thử nghiệm, học hỏi và tham gia cộng đồng NumPy.
Tài liệu tham khảo
- Truy cập trang web NumPy.org vào tháng 7 năm 2020.
- Kho lưu trữ NumPy trên GitHub.
- Hệ thống tài liệu. Divio.com được truy cập vào tháng 7 năm 2020.
- Dewey, John. Dân chủ và Giáo dục. Project Gutenberg, tháng 8 năm 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. Tháng 6/2005.