Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
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 GenPipes tại "Read The Docs"
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Tôi đề xuất một kế hoạch gồm 3 bước để đạt được mục tiêu thiết lập tài liệu GenPipes trên "Read The Docs".
Bước 1: 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 bị thiếu, không chính xác
- Đề xuất chủ đề tài liệu mới (nếu cần)
- Phác thảo cấu trúc thông tin để 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 tôi cũng có thể cần ý kiến đóng góp của các cố vấn GenPipes về việc 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. Bạn có thể cần phải tuân thủ 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 loại tiêu chuẩn, theo tôi được biết. 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à một mẫu mà tôi đã tạo cho đề xuất này)
Dựa trên việc xem xét và phân tích ở bước trước, hãy tạo một khung xương đơn giản của cấu trúc / chỉ mục Tài liệu GenPipes được đề xuất và đăng lên trang web RTD
- Việc này liên quan đến việc tạo kho lưu trữ GitHub (ví dụ: bằng công cụ Sphinx) và các tệp tài liệu cơ bản
- Ngoài ra, việc tạo mục tiêu mới cũng bao gồm việc tạo mục tóm tắt mới, giúp cân nhắc cả người dùng mới và người dùng dày dạn kinh nghiệm cho nhiều mục / luồng thông tin khác nhau.
Xem xét / yêu cầu phê duyệt mục lục chi tiết của bản thảo cơ bả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 nội dung này chỉ dành cho mục đích minh hoạ, đường liên kết được bảo vệ và chưa được đăng công khai trên RTD. Bất kể tôi có được chọn hay không, bản minh hoạ này có thể được dùng để bắt đầu nỗ lực RTD của GenPipes. Tôi đã kiểm tra các nguồn trong kho lưu trữ GitHub c3g/GenPipes. Các cố vấn, Rola và Hector đã thích nó trong cuộc thảo luận "chia sẻ màn hình" trên Skype trước đó, vì vậy, tôi nghĩ rằng các vị thần GSoD cũng muốn xem. Hiện tại, tôi chỉ có khung xương đơn giản nhưng dự định sẽ cập nhật khi có thời gian cho đến hết ngày 30 tháng 7.
https://genpipes.readthedocs.io/en/latest/
Bước 2: Tạo bộ tài liệu GenPipes Doc v0.9
Xác định tài liệu GenPipes hiện tại hoặc hiện có nào có thể được nhập, liên kết hoặc chuyển đổi thành tài liệu dựa trên Sphinx/rst để lưu trữ trên RTD, đồng thời lưu ý đến tiến trình GSoD
Chuyển đổi các tài liệu đã xác định sang định dạng rst (nếu cần), tạo các tài liệu mới nếu có thể, sử dụng lại mọi tài liệu có thể / liên quan.
- Nhập bộ tài liệu ban đầu này vào ReadTheDocs dưới dạng Bằng chứng về khái niệm – lưu trữ bộ tài liệu đó dưới dạng kho lưu trữ được bảo vệ. Đưa ra một 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 quá trình xem xét/chuyển đổi chính thức được phê duyệt.
Review/course-correct/update
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 vào mục Lục mục của GenPipes – Thêm tài liệu bổ sung bên cạnh một số tài liệu đầu tiên (GenPipes Readme), Khái niệm, Hướng dẫn, v.v.
Thêm ranh giới rõ ràng trong mục lục để giải quyết vấn đề cho 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ề một quy trình làm việc với tính năng tự động hoá một phần thông qua RTD (các bản dựng của sphinx) về cách duy trì, chỉnh sửa tài liệu của GenPipes cho người dùng và liệu C3G có cho phép những người đóng góp tài liệu bên ngoài làm như vậy hay không. Bạn có thể cần tạo một số nguyên tắc để cập nhật tài liệu tương tự như nguyên tắc lập trình. Có thể yêu cầu thêm các bước phụ. Ví dụ: tự động kiểm tra chính tả trước khi phê duyệt bài viết quan hệ công chúng trong tài liệu GenPipes.
Báo cáo
Cuối cùng, Tạo một báo cáo cho GSoD dựa trên trải nghiệm, nhật ký và ý kiến phản hồi của cố vấn.
Ý kiến khác
Trong tương lai (sau 3 tháng), nếu có thể, tôi có thể giúp duy trì việc này cho GenPipes trong thời gian dài hơn. Hoặc đào tạo những người khác (nếu cần) để làm tương tự. Chúng ta có thể tìm hiểu điều này dựa trên kết quả của 3 tháng đầu tiên.
Ngoài ra, tôi đề xuất thêm một ý tưởng đề xuất dự án – tạo một bản tóm tắt 3 trang về GenPipes để giúp bạn dễ dàng làm quen. Hiện nay, người dùng mới phải nhảy nhiều vòng trước khi có thể bắt đầu sử dụng GenPipes vì tài liệu hướng dẫn khá hữu ích nhưng rải rác và không hữu ích 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ử.
Bạn cũng có thể xem đề xuất này và quá trình hình thành đề xuất (nhật ký) tại https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing