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ở:
- GenPipes
- Người viết nội dung kỹ thuật:
- shaloo
- Tên dự án:
- Thiết lập tài liệu về GenPipes tại phần "Đọc tài liệu"
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Tôi đang đề xuất một kế hoạch gồm 3 bước để đạt được mục tiêu khi thiết lập tài liệu GenPipes về "Đọc tài liệu".
Bước 1: Đầu mối liên hệ (POC)
Xem lại 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 còn thiếu, không chính xác
- Đề xuất chủ đề về tài liệu mới (nếu cần)
- Cấu trúc thông tin nháp liên quan đến đối tượng mục tiêu, trong đó 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 của những người cố vấn GenPipes về cách thiết lập kho lưu trữ GitHub mới để lưu trữ các tài liệu 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. Bạn có thể phải có 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 tuân thủ. Nếu không, bạn có thể sử dụng các toán tử 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à bản 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 của cấu trúc / chỉ mục Tài liệu GenPipes đề xuất và đưa lên trang web của RTD
- Điều này liên quan đến 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
- Bên cạnh đó, bạn cũng sẽ tạo được một tài liệu hướng dẫn mới cho cả người dùng mới và người dùng dày dạn kinh nghiệm cho các phần / luồng thông tin khác nhau.
Xem xét / yêu cầu phê duyệt bảng điều khiển nội dung về bộ xương cơ bản
Trong giai đoạn đánh giá GSoD của GenPipes, tôi đã cố gắng tạo ra giá trị cho GenPipes thông qua mẫu được lưu trữ tại RTD. Xin lưu ý rằng việc này chỉ dùng cho mục đích minh hoạ, đường 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, bản minh hoạ này vẫn có thể dùng để khởi động dự án RTD của GenPipes. Tôi đã kiểm tra trong các nguồn trong kho lưu trữ GitHub c3g/GenPipes. Các cố vấn, Rola và Hector thích chương trình này trong buổi thảo luận "chia sẻ màn hình" của Skype trước đó nên tôi nghĩ có thể GSoD Gods cũng muốn xem. Hiện tại, bộ xương này vẫn còn mới 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/đầu tiên để lưu trữ trên RTD theo tiến trình của GSoD
Chuyển đổi các tài liệu đã xác định sang định dạng đầu tiên (nếu cần) rồi tạo tài liệu mới nếu phù hợp và sử dụng lại bất kỳ nội dung nào có thể / liên quan.
- Nhập tập hợ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ệ. Đăng thông báo trước khi đề 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 yêu cầu xem xét/chuyển đổi chính thức được thực hiện.
Xem lại/chính xác/cập nhật khoá học
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ủa GenPipes được đề xuất vào GenPipes terms – Thêm tài liệu bổ sung ngoài một số tài liệu đầu tiên (GenPipes Readme), Concepts, hướng dẫn, v.v.
Thêm thông tin phân cách rõ ràng trong terms để nhắm đến người dùng mới, người dùng dày dạn kinh nghiệm GenPipes, nhà phát triển GenPipes, v.v.
Đề xuất, thảo luận quy trình làm việc với tính năng tự động hoá một phần thông qua RTD (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 không. Bạn có thể phải tạo một số nguyên tắc tương tự như nguyên tắc lập trình để cập nhật tài liệu. Có thể yêu cầu thêm nhiều bước phụ. Ví dụ: tự động kiểm tra lỗi chính tả trước khi phê duyệt PR trong tài liệu về 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.
Cảm nghĩ khác
Trong tương lai (trên 3 tháng), nếu được, tôi có thể giúp duy trì chương trình này lâu dài hơn cho GenPipes. Hoặc đào tạo người khác nếu cần. Chúng ta có thể xác định điề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 gợi ý một ý tưởng khác về việc đề xuất dự án – tạo một bản tóm tắt về GenPipes 3 giúp bạn dễ dàng bắt đầu làm quen. Hiện nay, người dùng mới phải chuyển qua nhiều vòng lặp 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. 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ử xem.
Bạn cũng có thể xem đề xuất tương tự này và tác dụng của nó (nhật ký) tại https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing