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ở:
- NumPy
- Người viết nội dung kỹ thuật:
- hợp tác
- Tên dự án:
- Tài liệu của NumPy về giáo dục cộng đồng
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Giới thiệu
NumPy cung cấp điện toán dựa trên mảng sạch và nhanh chóng trong 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 cho tính toán khoa học [1]. Hơn 370 nghìn dự án đã sử dụng điện toán mảng hiệu quả [2]. Người dùng NumPy được chào đón bằng một trang web mới cung cấp các ứng dụng và nghiên cứu điển hình [1]. Khi người dùng mới tìm thấy trang tài liệu, họ sẽ thấy nhiều đường liên kết “Bắt đầu tại đây” và các hướng dẫn giới thiệu có thể gây choáng ngợp cho người mới bắt đầu, chẳng hạn như NumPy Basics/Trao đổi byte. Tôi bắt đầu sử dụng NumPy cách đây 10 năm khi còn học sau đại học. Tôi tự thấy mình kết hợp các bài đăng trên blog, ghi chú bài giảng và câu trả lời của StackExchange để tránh xem qua tài liệu về NumPy. Hiện có hơn 360 nghìn cuộc trò chuyện trên StackExchange liên quan đến NumPy. Tôi nghĩ rằng những người dùng khác cũng có lộ trình thành công tương tự trong NumPy. Nền tảng của các công cụ giáo dục là nền tảng giao tiếp và cộng đồng [4]. Tài liệu này cần xây dựng 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 là hướng dẫn nhất quán và rõ ràng cho người dùng mới. Các hướng dẫn này phải cung cấp cho người dùng mới các bước dễ thực hiện và tạo cảm giác thoải mái khi sử dụng thư viện [3]. Tài liệu này chào mừng người dùng mới gia nhập cộng đồng NumPy. Cấu trúc, nhịp độ và tác giả của tài liệu này đều cần tạo ra một không gian 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 thông tin còn thiếu trong tài liệu về NumPy hiện tại để giúp người dùng mới được hướng dẫn và chào mừng gia nhập cộng đồng.
Kiến thức mà người dùng thu được bằng cách kiểm tra và thử nghiệm [4,5]. Kiến thức phụ thuộc vào phương pháp thử nghiệm và đánh giá. Nội dung đưa ra mục tiêu và ứng dụng rõ ràng trong hướng dẫn cho phép người dùng thử nghiệm và đánh giá các ý tưởng cũng như phương pháp mới. Cộng đồng có thể xây dựng cơ sở kiến thức để 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 gấp đôi. Trước tiên, người dùng mới và người dùng có kinh nghiệm có một bộ mục tiêu rõ ràng để kiểm tra và xây dựng thử nghiệm. Thứ hai, những người đóng góp tài liệu tiềm năng sẽ có không gian để truyền đạt mục tiêu, phương pháp và giải pháp của mình. Việc cung cấp phần hướng dẫn là một nhu cầu tức thì để 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à người đóng góp tiềm năng. Kiến thức hiện tại
John Dewey cho rằng nền tảng của việc học tập là trải nghiệm chân thực [4]. Cộng đồng NumPy có một lượng rất lớn trải nghiệm chân thực có thể được chia sẻ với những người dùng khác. Giáo dục được xây dựng dựa trên cộng đồng và giao tiếp. Trang tài liệu có bố cục gọn gàng sẽ 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 truyền đạt các trải nghiệm trong NumPy.
Có 4 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 chiếu. Tài liệu về NumPy có một số tài liệu trong không gian hướng dẫn kết hợp nội dung giải thích và nội dung cách chèn vào phần hướng dẫn. Không gian hướng dẫn nên 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 các quy trình đị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ào các chuỗi tài liệu chi tiết của mỗi chức năng. Phần hướng dẫn và không gian hướng dẫn hiện tại không được mô tả rõ ràng và đôi khi được đưa vào phần giải thích và tham khảo. Có một hướng dẫn rất hiệu quả cho khoá học "Cơ bản dành cho người mới bắt đầu" và người dùng Matlab có một tài liệu rất hữu ích để tạo mã NumPy trong phần "Numpy cho người dùng Matlab". Việc mô tả rõ ràng 4 dấu cách này sẽ giúp tài liệu trở nên 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ự khác biệt rõ ràng giữa hướng dẫn, cách thực hiện, phần giải thích và không gian tham khảo. Điều này khiến cộng tác viên tiềm năng bị nhầm lẫn. Người dùng mới có thể bị choáng ngợp trước phần giải thích và tài liệu tham khảo trong phần hướng dẫn và những người đóng góp tiềm năng có thể gặp khó khăn khi đóng góp. Tôi đề xuất một bố cục dễ tiếp cận hơn cho người mới tham gia và những người có thể là đóng góp tài liệu với luồng logic trong tài liệu và quản lý các yêu cầu lấy dữ liệu cho tài liệu hướng dẫn do người dùng đóng góp của những người đóng góp mới. 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 hỏi qua các tài liệu là một trải nghiệm giáo dục và giao tiếp bổ ích và mang lại. Mô hình tài liệu này giúp nền tảng giáo dục qua trải nghiệm thực tế cho những người mới tham gia và người đóng góp tiềm năng.
Lý do
Đề xuất về Google Tài liệu cho mùa hè này rất quan trọng đối với mục tiêu sư phạm và sự nghiệp của tôi. Tôi sử dụng NumPy và SciPy trong tất cả các khóa học của mình. Học sinh của tôi gặp khó khăn trong việc sử dụng tài liệu hiện tại. Tôi muốn vận dụng kinh nghiệm của mình trong việc dạy cách lập trình cho các chuyên ngành không phải CS để hỗ trợ sắp xếp, chỉnh sửa và bổ sung thông tin còn thiếu trong các hướng dẫn hiện tại. Sau đó, tôi có thể sử dụng tài liệu đó 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ụ sử dụng Python và
Mục tiêu cụ thể
Tôi có ba mục tiêu cụ thể cho đề xuất mùa hè của Google Tài liệu này: 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 chiếu vào Không gian giải thích, và 3. Xây dựng tài liệu hướng dẫn với học viên. Mỗi mục tiêu cụ thể đều có kết quả dự kiến cho đề xuất.
Ba mục đích cụ thể này là để làm cho tài liệu trở nên dễ tiếp cận hơn đối với người dùng mới và tạo cấu trúc cho cộng tác viên tiềm năng. Mục đích 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ả mong đợi
Tôi có ba kết quả dự kiến như sau: 1. Một trang web tài liệu đã sửa đổi phân tách rõ ràng bốn không gian: hướng dẫn, cách làm, giải thích và tài liệu tham khảo, 2. hướng dẫn mới về: đọ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 so với phần tử trong NumPy, và 3. 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ộ trên tài liệu, cung cấp cho những người đóng góp tài liệu tiềm năng về những phong cách và định dạng rõ ràng, làm cho các hướng dẫn hiện tại ngắn hơn và dễ theo dõi hơn, chuyển nội dung giải thích sang một phần riêng và 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ỏ cho phần hướng dẫn mà không cần xây dựng toàn bộ tài liệu về 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 xây dựng toàn bộ tài liệu về 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 được đề xuất này sẽ bắt chước tài liệu nguồn mở hiện tại như Matplotlib, Divio, v.v. Người dùng mới và 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 trường và phần mềm của họ.
Thời gian thực hiện dự án: 14/9 – 30/11. Bước đầu tiên là xây dựng tài liệu và tách riêng nội dung trong các hướng dẫn hiện tại thành nội dung Hướng dẫn, Hướng dẫn và Giải thích. Việc này sẽ được thực hiện trong năm tuần đầu tiên của dự án trong khuôn khổ Kết quả 1 và 2 là sửa đổi trang web và hướng dẫn tương ứng. Tổ chức Tài liệu được đề xuất được nêu trong Tài liệu được đề 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á cài đặt, có thể thay thế tính năng nhập/xuất gấu trúc bằng numpy.loadtxt không?)
- liên kết đến “What is numpy”
- đườ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ùng để tiếp nối hướng dẫn về Python)
- Làm việc với các mảng NumPy
- tạo mảng (np.zeros, np.ones, np.block, v.v.) (ghi: mức độ ưu tiên trung bình thấp)
- phép toán tử tương ứng (+,-,*,/) và phép toán đại số tuyến tính (+,-,@, linalg.solve) (ghi:ưu tiên med)
- Đọ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à mô tả và có thể thay đổi tiêu đề thành "Xử lý hình ảnh bằng đại số tuyến tính Numpy")
- đường liên kết đến nội dung hướng dẫn dạng numpy (bài tập đang thực hiện)
iii. Giải thích:
- Kiểu 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
- Ghi vùng chứa mảng tuỳ chỉnh
- phân 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 API Numpy
- Numpy 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 cuộc thảo luận mảng/ma trận gây mất tập trung và có vẻ không được dùng nữa)
Sau khi hoàn thành Phần Google Tài liệu này, tôi đề xuất những kết quả sau:
- 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, Hướng dẫn, Giải thích và Tài liệu tham khảo
- Hướng dẫn mới về: tạo mảng (np.zeros, np.ones, np.block, v.v.), phép toán tương ứng với phần tử (+,-,*,/) và phép toán đại số tuyến tính (+,-,@, linalg.solve), cũng như Đọc và ghi dữ liệu bằng Numpy (mức độ ưu tiên cao)
- Đưa ra tài liệu hướng dẫn để tăng sự đóng góp của người dùng và giúp đạt được mục tiêu của cộng đồng trong việc dạy và học
Mỗi kết quả có một số bước được nêu dưới đây trong các bảng Kết quả 1-3. Trong khi Tài liệu đề xuất được gửi đi xem xét, hướng dẫn "Đọc/ghi mảng" có mức độ ưu tiên cao sẽ được viết để gửi dưới dạng yêu cầu lấy dữ liệu trong Kết quả 2. Trong quá trình xem xét trang web sửa đổi và cập nhật hướng dẫn "Đọc/Ghi mảng", 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 lấy dữ liệu (pull request) và bắt đầu viết hướng dẫn về hạng 3: Các phép toán đại số tuyến tính và phần tử trong Python.
Kết quả thứ ba là tư vấn cho sinh viên tại Đại học Connecticut xây dựng tài liệu trong kho lưu trữ hướng dẫn numpy. Các tài liệu hướng dẫn hoặc tài liệu hướng dẫn bạn gửi sẽ là những sổ tay Jupyter sử dụng NumPy để giải quyết các vấn đề kỹ thuật. Tôi 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 làm theo bố cục và cấu trúc khi học sinh tạo mẫu và lược đồ tạo 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 đối tượng rộng hơn. Đây là một cơ hội tuyệt vời để sinh viên tham gia vào cộng đồng NumPy và học hỏi.
Kết quả 1: Sửa đổi trang web Deliverable Date Fork Repository và Build Tài liệu với Sphinx 9/21 Xây dựng trang web với Bốn không gian được xác định và liên kết 10/1 Chuyển 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 cho github với những thay đổi đề xuất 11/1 Phản hồi các nhận xét/đề xuất và sửa đổi PR đang diễn ra với Kết quả 1/30 đã sửa đổi trang web
Kết quả 2: Sửa đổi ngày hướng dẫn PR
Thứ hạng đề xuất cho các bản sửa đổi phần hướng dẫn (có thể thay đổi tuỳ theo 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 giải thích và minh hoạ các công cụ tạo/tương tác mảng phổ biến
Các phép toán đại số tuyến tính và dạng phần tử (+,-,*,/ và +,-@,linalg.solve) Không tồn tại: điều này đặc biệt hữu ích đối với 1. Người dùng Matlab và 2. Những người áp dụng đạ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 chọn lọc Ngày có thể gửi đến Đường liên kết bên ngoài(vấn đề/ví dụ)
Xây dựng Ví dụ hướng dẫn (đề xuất: Cách tìm tần số tự nhiên của dây đàn ghi-ta 10/20
Tạo mẫu Hướng dẫn cho người đóng góp mới 10/1 Mẫu hướng dẫn PR và Đóng góp những đóng góp có thể có
Làm việc với những người đóng góp khác để xây dựng sổ tay Hướng dẫn tuyển dụng học viên/các thành viên khác trong cộng đồng được phê duyệt) 7
Tầm quan trọng dự kiến
Đề xuất Mùa hè tài liệu của Google này sẽ giúp tài liệu NumPy , điền vào các hướng dẫn còn thiếu từ trang web và thu hút những người đóng góp vào tài liệu. Là Giáo sư ngành Kỹ thuật cơ khí, tôi dự định phân đoạn tài liệu theo cách mà sinh viên có thể điều hướng trong tài liệu và dễ dàng tìm thấy hướng dẫn nhập môn so với hướng dẫn thực hành. Tài liệu theo phân đoạn: hướng dẫn, cách thực hiện, tài liệu tham khảo và nội dung giải thích sẽ cung cấp ví dụ có cấu trúc cho cộng tác viên tiềm năng để xây dựng tài nguyên mới. Tài liệu được đề xuất thể hiện quan điểm "cho nhận và nhận" thông qua trải nghiệm giáo dục 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 đề xuất tư vấn cho sinh viên Đại học Connecticut sẽ khiến ý tưởng giáo dục và giao tiếp này trở thành hiện thực. 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
- Trang web NumPy.org truy cập ngày 07/07/2020.
- Kho lưu trữ NumPy trên GitHub.
- Hệ thống tài liệu. Truy cập Divio.com ngày 07/2020.
- Dewey, John. Dân chủ và giáo dục. Dự án Gutenberg, tháng 8 năm 2015.
- Dewey, John. Nhiệm vụ chắc chắn George Allen và Unwin Limited. 06/2005.