Dự án GenPipes

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 Google Phần Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
GenPipes
Người viết nội dung kỹ thuật:
shaloo
Tên dự án:
Thiết lập tài liệu của GenPipes tại phần "Đọc tài liệu"
Thời lượng dự án:
Thời lượng tiêu chuẩn (3 tháng)

Mô tả dự án

Tôi đang đề xuất một kế hoạch 3 bước để đạt được mục tiêu thiết lập tài liệu của GenPipes về "Đọc tài liệu".

Bước 1: Đầu mối liên hệ (POC)

  • Xem tài liệu hiện có về GenPipes với tư cách là người dùng / nhà nghiên cứu mới

    • Xác định thông tin bị thiếu, không chính xác
    • Đề xuất chủ đề tài liệu mới (nếu cần)
    • Bản nháp cấu trúc thông tin cần nhắm đến đối tượng mục tiêu, tập trung vào người dùng mới.

    (Lưu ý: Trong bước này, chúng ta cũng có thể cần thông tin đầu vào từ các cố vấn của GenPipes về cách thiết lập kho lưu trữ GitHub mới để lưu trữ tài liệu về genpipes cho RTD. Bạn có thể dùng kho lưu trữ GitHub này để nhập tất cả tài liệu trong quy trình xây dựng RTD. Để làm được như vậy, bạn có thể phải xem thông tin chi tiết về các quy tắc kho lưu trữ GenPipes và nguyên tắc quản lý nguồn tài liệu (nếu cần). Nếu không, bạn có thể sử dụng các mã tiêu chuẩn. Ngoài ra, đối với PoC, tôi có thể minh hoạ cách thiết lập kho lưu trữ RTD mẫu bằng tài khoản GitHub của mình – ví dụ: https://gpdocs.readthedocs.io/en/latest/ – đây là trình lấy mẫu mà tôi đã tạo cho đề xuất này)

  • Dựa trên kết quả xem xét và phân tích ở bước trước, hãy tạo một bộ khung cơ bản cho cấu trúc / chỉ mục Tài liệu GenPipes đề xuất và đưa lên trang web RTD

    • Quá trình này bao gồm việc tạo kho lưu trữ GitHub (ví dụ: với công cụ Sphinx) và các tệp tài liệu cơ bản
    • Việc này cũng liên quan đến một tính năng tạo tài khoản mới giúp lưu ý đến cả người dùng mới và người sử dụng dày dạn kinh nghiệm cho các mục / luồng thông tin khác nhau.

  • Xem xét / yêu cầu phê duyệt đối với khung xương trần

    Trong giai đoạn đánh giá GSoD của GenPipes, tôi đã cố gắng tạo giá trị cho GenPipes thông qua mẫu này được lưu trữ tại RTD. Xin lưu ý rằng việc này chỉ nhằm mục đích minh hoạ, liên kết được bảo vệ, chưa được đăng công khai trên RTD. Bất kể tôi có được đưa vào danh sách rút gọn hay không, tôi vẫn có thể sử dụng bản minh hoạ này để bắt đầu dự án RTD của GenPipes. Tôi đã kiểm tra trong các nguồn trong kho lưu trữ GitHub c3g/GenPipes. Những cố vấn viên, Rola và Hector thích phần này trong lúc thảo luận về "chia sẻ màn hình" qua Skype trước đó và vì vậy tôi nghĩ có thể các vị thần của GSoD cũng muốn xem. Hiện tại thì vẫn chưa có bộ xương cơ bản nào nhưng tôi dự định sẽ cập nhật khi thời gian cho phép đến hết ngày 30 tháng 7.

https://genpipes.readthedocs.io/en/latest/

Bước 2: Tạo tài liệu GenPipes Doc v0.9

  • Xác định những tài liệu GenPipes hiện có hoặc hiện có có thể được nhập, liên kết hoặc chuyển đổi sang tài liệu dựa trên Sphinx/rst để lưu trữ trên RTD có tính đến dòng thời gian của GSoD

  • Chuyển đổi tài liệu đã xác định sang định dạng rst (nếu cần), tạo tài liệu mới (nếu phù hợp) và sử dụng lại mọi tài liệu có thể / phù hợp.

    • Nhập tài liệu ban đầu này vào ReadTheDocs dưới dạng Proof of Concept – lưu trữ tài liệu đó ở đó dưới dạng kho lưu trữ được bảo vệ. Ghi chú trước để đề xuất người dùng mới truy cập vào tài liệu gốc của GenPipes cho đến khi bạn xem xét/chuyển đổi chính thức.

  • Đánh giá/khoá học-chính xác/cập nhật

Bước 3: Tinh chỉnh, xem lại và xuất bản bản nháp đầu tiên tại RTD

  • Điền thông tin chi tiết về cấu trúc tài liệu mới được đề xuất của GenPipes vào GenPipes ô – Thêm các tài liệu bổ sung ngoài một số tài liệu đầu tiên (GenPipes Readme), Concepts,!

  • Thêm thông tin phân định rõ ràng trong UMP để nhắm đến người dùng mới, người dùng GenPipes dày dạn kinh nghiệm, nhà phát triển GenPipes, v.v.

  • Đề xuất, thảo luận về quy trình làm việc có tự động hoá một phần thông qua RTD (các bản dựng nhân sư) về cách người dùng có thể duy trì, chỉnh sửa tài liệu của GenPipes và liệu C3G có cho phép những người đóng góp tài liệu bên ngoài hay không. Việc này có thể yêu cầu tạo một số nguyên tắc để cập nhật tài liệu, tương tự như trong nguyên tắc lập trình. Bạn có thể phải thực hiện thêm các bước phụ. Ví dụ: Tự động kiểm tra lỗi chính tả trước khi phê duyệt PR trong các tài liệu của GenPipes.

Báo cáo

Cuối cùng, hãy tạo một báo cáo cho GSoD dựa trên kinh nghiệm, nhật ký và ý kiến phản hồi của người cố vấn.

Suy nghĩ khác

Trong tương lai (sau 3 tháng), nếu được, tôi có thể giúp duy trì vấn đề này cho GenPipes về lâu dài. Hoặc đào tạo người khác (nếu cần) để làm theo cách tương tự. Chúng tôi có thể xác định mục tiêu này dựa trên kết quả của 3 tháng đầu tiên.

Ngoài ra, tôi cũng đề xuất thêm ý tưởng đề xuất dự án khác, đó là tạo một bản tóm tắt trang GenPipes 3 để giúp bạn dễ dàng làm quen. Ngày nay, người dùng mới phải sử dụng nhiều nội dung thay đổi trước khi có thể bắt đầu sử dụng GenPipes vì tài liệu này hữu ích nhưng phân tán và không có lợi cho người dùng mới. Tôi không chắc liệu có thể thực hiện việc này trong vòng 3 tháng hay không, nhưng tôi muốn thử thực hiện.

Bạn cũng có thể xem đề xuất tương tự và cách xuất hiện (lịch sử) tại https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing