Trang này được dịch bởi Cloud Translation API.

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 tài liệu của Google.

Tóm tắt dự án

Tổ chức nguồn mở:: Matplotlib
Tác giả kỹ thuật:: jeromev
Tên dự án:: Phát triển đường dẫn mục nhập Matplotlib
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

Đề xuất dự án của Matplotlib cho Google Season of Docs năm nay là 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 mục 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à người mới viết chuyên môn về kỹ thuật trong ngành này; tuy nhiên, kiến thức nền của tôi là trong các lĩnh vực giáo dục và giáo dục. Nội dung viết về kỹ thuật và nội dung giáo dục có nhiều điểm tương đồng, tập trung vào việc tạo ra nội dung đồng cảm và giúp người dùng hoàn thành công việc bằng các tài nguyên được cung cấp.

Trong trường hợp này, tài liệu Matplotlib sẽ được cải thiện trong việc đồng cảm với người dùng mới. Hiện tại, phần lớn tài liệu bao gồm dữ liệu được tạo ngẫu nhiên và hình ảnh không được gắn nhãn. Đây là những cách tuyệt vời để nhanh chóng hiển thị 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, việc chuyển đổi dữ liệu thành hình ảnh sẽ gặp nhiều khó khăn.

Ngữ cảnh trong phương pháp giải thích là giải pháp cho trở ngại này. Bằng cách viết một quy trình thông qua ví dụ 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 về việc đạt được mục tiêu hoặc kỳ vọng hoàn thành một nhiệm vụ.

Người dùng có một mục đích phái sinh nhất quán. Ví dụ: nhà khoa học dữ liệu tại một 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ạ các xu hướng mua sắm theo thời gian. Trong trường hợp này, người dùng phải tìm hiểu cách điều hướng 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 có bối cảnh bổ sung hỗ trợ tài liệu, người dùng mới có thể dễ nhận biết chủ đề đó hơn. Mục đích phái sinh của người dùng song song với tài liệu. Tôi hy vọng có thể 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ó một người thực sự có thể viết và đồng cảm với người dùng, để xem xét và về cơ bản viết một cuốn sách "Giới thiệu về Matplotlib" dài 200 trang và đó là mục chính trong tài liệu".

Phương pháp tiếp cận khác đối với nội dung 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 này. Ví dụ: hướng dẫn thường tuân theo mẫu không giải thích phương thức cơ bản.

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

Thường thì với tài liệu lập trình và dịch vụ hỗ trợ, người dùng nên tự chạy mã để hiểu những gì đang xảy ra. Mặc dù tư duy lập trình giúp người dùng hiểu rõ hơn về chủ đề này, nhưng quá trình học về các phép biến đổi lại có ít nội dung hỗ trợ. Đây có thể là một thách thức lớn vì tài liệu còn hạn chế.

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

{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 có tiềm năng to lớn trong việc sử dụng văn bản giải thích cho tài liệu. Khi người dùng thấy nhiều khái niệm về phép biến đổi, họ sẽ có thể xác định rõ hơn các chiến lược cơ bản để 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 cải tiến và tận dụng các tính năng được trình bày bằng các ví dụ dựa trên 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 việc dễ sử dụng và dễ tiếp cận là minh chứng cho danh tiếng của thư viện này. Những đặc điểm này giúp minh hoạ các mẫu và chiến lược phổ biến không chỉ xuất hiện trong mã mà còn trong tài liệu. Nếu Matplotlib đơn giản và chuẩn hoá để người dùng lập trình, như thể hiện trong việc sử dụng ngày càng tăng và mở rộng tài nguyên, thì Matplotlib cũng có thể như vậy đối với tài liệu kỹ thuật.

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

Điều này sẽ liên quan đến 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 phong phú các đường liên kết đến các chủ đề tương đồng cũng như các chủ đề thông tin sẽ giúp xây dựng một mạng lưới mạnh mẽ. Trong mạng lưới này, người dùng có nhiều khả năng tiếp tục sử dụng tài liệu 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ủ đề đó.

Vật cản

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à văn kỹ thuật mới trong ngành, tôi có ít kinh nghiệm sử dụng Sphinx và ReST để viết tài liệu. Tôi cũng là một người mới bắt đầu khi nói đến Matplotlib cũng như Git. Việc xử lý 4 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 sẽ tốn thời gian. Tôi sẽ cần dành 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 cấp nhập môn. Trong thời gian này, nếu gặp vấn đề về các khái niệm và kiến thức cơ bản, tôi sẽ cần liên hệ với cộng đồng để được hỗ trợ thêm.

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

Ngoài ra, việc 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ẽ mang lại lợi ích cho các đường dẫn truy cập của Matplotlib. Việc tiến hành khảo sát về khả năng hữu dụng của nội dung nhằm mục đích cung cấp hồ sơ người dùng, tức là các personas. Thông tin như trải nghiệm của người dùng, ngành nghề của họ và nhật ký khắc phục sự cố đều có giá trị. Các phần này giúp tạo thành ngôn ngữ đằng sau quy trình. Khi nội dung phù hợp với trình độ của độc giả, nội dung sẽ trở nên hoàn thiện hơn chứ không chỉ đơn thuần là nội dung hướng dẫn.

Vấn đề lớn thường nằm ở việc tạo ra một phương pháp kiểm thử khả năng hữu dụng liên tục. Thông thường, bạn chỉ kiểm thử một lần (nếu có) trong quá trình phát triển nội dung. Việc kiểm thử khả năng hữu dụng thường xuyên sẽ giúp thúc đẩy câu chuyện của nội dung. Tôi hy vọng có thể thiết lập lịch trình hoặc tổ chức các bài kiểm thử khả năng hữu dụng định kỳ với cộng đồng Matplotlib.

Kết luận

Tôi có một chút kinh nghiệm sử dụng Python cũng như Matplotlib trong thời gian rảnh. Trong vài tháng qua, tôi đã tự học được nhiều kiến thức nhờ tài liệu hiện có và sự tò mò của bản thân. Tôi cũng đã từng tham gia một số video và cố vấn trong thời gian đó. Tôi vẫn còn nhiều điều phải học và thậm chí còn có nhiều cơ hội để cải thiện khi tự xây dựng chương trình học lập trình mà tôi quan tâm.

Sau khi xem các ý tưởng mà Matplotlib và cộng đồng có cho GSoD, tôi cảm thấy đây sẽ 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ình với tư cách là một nhà văn kỹ thuật và có cơ hội tìm hiểu thêm từ những người đứng sau 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ê về mặt lý tưởng.

Để hoàn 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 nhiệm vụ họ muốn mà không bị choáng ngợp trước các tính năng có sẵn. Tôi tin rằng tài liệu tốt nhất sẽ tiếp tục phát triển và thích ứng với người dùng, đồng thời cho phép mọi người dùng chuyển sang giải pháp của riêng họ.