Dự án Matplotlib

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ở:

Matplotlib

Người viết nội dung kỹ thuật:

jeromv

Tên dự án:

Phát triển đường dẫn nhập Matplotlib

Thời lượng dự án:

Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

Giới thiệu

Đề xuất dự án của Matplotlib cho Mùa Google Tài liệu năm nay liên quan đến việc tạo nội dung giúp giới thiệu Matplotlib cho người dùng mới. Để phát triển Đường dẫn nhập Matplotlib, tôi đề xuất một phương pháp thay thế cho tài liệu hiện tại. Tôi là một người mới viết về kỹ thuật trong ngành. Tuy nhiên, chuyên môn của tôi là trong các lĩnh vực liên quan đến giáo dục và giáo dục. Nội dung về kỹ thuật và giáo dục có sự tương đồng mạnh mẽ khi tập trung vào việc sản xuất nội dung giúp mang lại sự đồng cảm và cho phép người dùng hoàn thành nhiệm vụ của họ thông qua các tài nguyên được cung cấp.

Trong trường hợp này, tài liệu về Matplotlib sẽ được cải thiện trong việc thể hiện sự đồng cảm với người dùng mới. Hiện tại, hầu hết nội dung đều có dữ liệu ngẫu nhiên và hình ảnh không có nhãn. Các hàm này rất hiệu quả trong việc hiển thị nhanh hình ảnh và các tính năng của Matplotlib. Tuy nhiên, đối với trường hợp sử dụng của người mới sử dụng Matplotlib, rất khó để truyền tải quá trình chuyển đổi dữ liệu thành hình ảnh.

Bối cảnh theo cách tiếp cận mang tính thực tế là một giải pháp cho trở ngại này. Bằng cách viết một quy trình thông qua lăng kính ví dụ trong thực tế, chúng ta đang thể hiện sự hiểu biết về môi trường mà người dùng làm việc. Điều này giúp cải thiện mối quan hệ giữa tài liệu và người dùng liên quan đến việc đạt được mục tiêu hoặc kỳ vọng về việc hoàn thành một nhiệm vụ.

Một người dùng có mục đích nhất quán (ví dụ: một nhà khoa học dữ liệu của công ty giày) phải trình bày dữ liệu khách hàng cho một nhóm để minh hoạ xu hướng mua sắm theo thời gian. Trong trường hợp này, người dùng phải học cách điều hướng trong Matplotlib và tận dụng các công cụ trong thư viện để hoàn thành nhiệm vụ hiện tại.

Khi tài liệu này có bối cảnh bổ sung, có thể người dùng mới sẽ dễ nhận biết được chủ đề đó hơn. Mục đích bắt nguồn của người dùng song song với tài liệu. Tôi hy vọng sẽ hướng tới tầm nhìn mà Nhà phát triển chính Tom Caswell đã thảo luận trong một cuộc phỏng vấn vào năm 2017 là “có ai đó thực sự có thể viết và đồng cảm với người dùng, trải qua và về cơ bản là viết cuốn sách 'Giới thiệu về Matplotlib' dài 200 trang, và đó là tài liệu chính."

Phương pháp thay thế cho cách viết bài thuyết trình

Tài liệu hiện tại minh hoạ các tính năng của Matplotlib, tức là những việc người dùng có thể làm với thư viện. Ví dụ: một hướng dẫn thường tuân theo mẫu không liên quan đến nội dung giải thích về phương thức cơ bản.

{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}

Thông thường, với tài liệu và sự hỗ trợ lập trình, người dùng nên tự chạy mã để hiểu điều gì sẽ xảy ra. Mặc dù tư duy lập trình giúp cải thiện hiểu biết của người dùng về chủ đề, nhưng lộ trình học tập cho việc chuyển đổi có ít nội dung hỗ trợ. Đây có thể là một thách thức quá lớn vì tài liệu có hạn.

Việc cung cấp biểu đồ, hình ảnh bổ sung hoặc các yếu tố trực quan khác sẽ giúp tạo ra cơ hội học tập mới. Cấu trúc dưới đây cũng là mẫu cho nội dung mới. Ngoài ra, việc thêm hình ảnh hoặc đồ hoạ không có văn bản có thể mang lại lợi ích từ các tính năng như chú thích và chú thích. Đôi khi, hình ảnh trở nên khó điều hướng hơn nếu không có chỉ báo về cách thức hoặc nơi mã được chuyển đổi thành kết quả được thực thi. Tôi tin rằng vẫn thiếu yếu tố hình ảnh ấn tượng có thể giúp người dùng hiểu rõ hơn về các chủ đề này.

{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}

Phương pháp thay thế này về việc sử dụng phần văn bản thuyết minh cho tài liệu có tiềm năng rất lớn. Khi người dùng nhìn thấy nhiều khái niệm về phép biến đổi, họ sẽ có thể xác định chính xác hơn các chiến lược cơ bản dùng để phát triển hình ảnh trực quan cho dữ liệu. Kiến thức này có thể giúp người dùng đổi mới và tận dụng các tính năng như trình bày trong các ví dụ ở các trường hợp sử dụng thực tế.

Khi Matplotlib ngày càng phổ biến, tính nhất quán trong cách sử dụng và khả năng tiếp cận là minh chứng cho danh tiếng của thư viện. Các đặc điểm này giúp thể hiện các mẫu và chiến lược phổ biến không chỉ trong mã mà còn trong tài liệu. Nếu Matplotlib đơn giản và là tiêu chuẩn để người dùng lập trình, thể hiện rõ trong việc sử dụng ngày càng nhiều và tài nguyên mở rộng, thì cũng có thể là cách dành cho tài liệu kỹ thuật.

Khi gặp vấn đề, người dùng thường sử dụng công cụ tìm kiếm để giải quyết chúng. Thay vì coi tìm kiếm làm phương thức di chuyển chính, việc cho phép người dùng tự xây dựng chương trình học trong tài liệu có thể mang lại tác động lớn hơn. Theo nghĩa này, người dùng tìm kiếm giải pháp cho vấn đề của họ, sau đó khi gặp vấn đề khác hoặc muốn có thêm thông tin, họ sẽ sử dụng các liên kết được nhúng và kỹ lưỡng một cách xuyên suốt.

Quy trình này bao gồm một cấu trúc từ dưới lên trong hệ thống tổ chức. Đối với mỗi chủ đề trong Matplotlib, một mạng lưới liên kết phong phú tới các đối tượng chung sở thích cũng như các chủ đề cung cấp thông tin sẽ giúp xây dựng một mạng lưới vững mạnh. Trong toàn bộ mạng này, người dùng sẽ có nhiều khả năng tiếp tục sử dụng tài liệu hơn khi họ chuyển đến chủ đề của mình và khám phá thêm nhiều thông tin liên quan đến chủ đề đó.

C chướng ngại vật

Với một dự án toàn diện và chi tiết như thế này, luôn có những thách thức. Là một nhà viết kỹ thuật mới trong ngành, tôi có ít kinh nghiệm về việc sử dụng Sphinx và ReST để viết tài liệu. Tôi cũng là người mới bắt đầu khi nói đến Matplotlib cũng như Git. Bạn sẽ cần thời gian để xử lý bốn hệ thống này và làm quen với việc sử dụng chúng để cộng tác và nghiên cứu. Tôi sẽ cần bố trí thời gian trong giai đoạn gắn kết cộng đồng và trước đó để xây dựng nền tảng cần thiết cho các lộ trình cho người mới bắt đầu. Trong thời gian này, nếu gặp vấn đề về khái niệm và nguyên tắc cơ bản, tôi cần liên hệ với cộng đồng để được hỗ trợ thêm.

Việc phối hợp các nỗ lực cộng tác trên các múi giờ và trên các nền tảng trực tuyến cũng sẽ có một số điều chỉnh. Có rất nhiều cách thức giao tiếp mà mọi người trong ngành này đều sử dụng, vì vậy cần phải đảm bảo rằng mình có thể tiếp cận và tiếp cận được ở mọi phương tiện. Tôi sẽ thông báo rõ ràng về mức độ ưu tiên của mình đối với các kỳ vọng khác nhau. Mặc dù chỉ mới bắt đầu đảm nhận những công việc như vậy trong ngành, nhưng tôi quan tâm đến việc chịu trách nhiệm cho bản thân và sẵn sàng đón nhận ý kiến phản hồi cũng như lời phê bình. Tôi cảm thấy những phẩm chất này có giá trị bất kể lĩnh vực nào.

Ngoài ra, tăng cường kiểm thử khả năng hữu dụng là một phần tài liệu mà tôi tin rằng sẽ có lợi cho đường dẫn nhập của Matplotlib. Việc tiến hành khảo sát về khả năng hữu dụng liên quan đến nội dung sẽ phục vụ mục đích cung cấp hồ sơ của một người dùng, cụ thể là chân dung độc giả. Những thông tin như trải nghiệm của người dùng, ngành và lịch sử khắc phục sự cố của họ đều có giá trị. Những phần này giúp hình thành ngôn ngữ cho quy trình. Khi hoạt động viết đáp ứng độc giả ở cấp độ của họ, nội dung không chỉ mang tính chất hướng dẫn mà còn trưởng thành.

Khó khăn lớn thường liên quan đến việc liên tục thử nghiệm tính hữu dụng. Việc triển khai một trường hợp thử nghiệm duy nhất (nếu được thực hiện) trong quá trình phát triển nội dung là quá phổ biến. Việc thường xuyên kiểm tra khả năng hữu dụng sẽ giúp thúc đẩy câu chuyện của nội dung. Tôi hy vọng có thể lên lịch hoặc kiểm tra khả năng hữu dụng định kỳ với cộng đồng Matplotlib.

Kết luận

Tôi có ít kinh nghiệm về việc sử dụng Python cũng như Matplotlib khi rảnh. Số tiền tôi đã tự học được trong vài tháng qua là nhờ sự hỗ trợ của tài liệu hiện tại và sự tò mò của chính tôi. Tôi cũng có một số video và người hướng dẫn của tôi trong khoảng thời gian đó. Tôi vẫn còn nhiều điều để học và thậm chí còn nhiều điểm hơn để cải thiện khi xây dựng chương trình học lập trình mà tôi quan tâm của riêng mình.

Sau khi xem ý tưởng của Matplotlib và cộng đồng dành cho GSoD, tôi cảm thấy đây là một trải nghiệm phát triển tuyệt vời để cải thiện kỹ năng của một người viết nội dung kỹ thuật, đồng thời có cơ hội học hỏi thêm từ những người ở hậu trường. Tôi cảm thấy dự án Matplotlib này vừa có ý nghĩa vừa là điều tôi đam mê trong hệ tư tưởng.

Để cải thiện hướng dẫn sử dụng, mục tiêu của tôi với tư cách là người viết nội dung kỹ thuật là giúp người dùng hoàn thành công việc họ muốn mà không bị choáng ngợp bởi các tính năng có sẵn. Tôi tin rằng tài liệu hiệu quả nhất sẽ tiếp tục phát triển và phù hợp với người dùng, cũng như giúp mọi người dùng tự tìm ra giải pháp của riêng mình.