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ở:
- CERN-HSF
- Người viết nội dung kỹ thuật:
- SabitaR
- Tên dự án:
- Điều chỉnh cấu trúc và đơn giản hoá tài liệu Allpix Squared
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
TỔNG QUAN Tôi đã chọn dự án Allpix Squared của CERN-HSF vì hai lý do chính:
Nâng cao kỹ năng: Tài liệu hiện có của dự án này rất toàn diện và tích hợp nhiều định dạng nội dung. Việc kiểm tra và sắp xếp lại bộ tài liệu toàn diện này sẽ giúp tôi trau dồi kỹ năng viết thông tin và kiến trúc của mình. Ngoài ra, tôi chưa quen với lĩnh vực của dự án (vật lý hạt!). Điều này giúp tôi rèn giũa kỹ năng tương tác với nhà phát triển. Tôi tin rằng các nhà văn kỹ thuật có thể xử lý thông tin đầu vào của nhà phát triển và trình bày nội dung hữu ích cho mọi cấp độ người dùng, MỘT KHI chúng ta thực hiện nghiên cứu cần thiết và đặt câu hỏi phù hợp. Dự án này sẽ cho phép tôi kiểm tra lý thuyết này!
Kiến thức kỹ thuật: Dự án này yêu cầu Hugo – một công cụ đứng đầu danh sách những kiến thức tôi cần học. Tôi rất mong được tìm hiểu quy trình làm việc LaTeX-Markdown-Hugo-GitLab-CI.
Trong giai đoạn khám phá vai trò nhà văn kỹ thuật, tôi đã trao đổi ngắn gọn với các cố vấn dự án và làm quen với cấu trúc bộ tài liệu hiện có. Tôi cũng đã tạo một trang web minh hoạ (https://ap2-demo.netlify.app/) để kiểm tra xem tôi có thể định cấu hình Hugo và Docsy chính xác trên máy Windows hay không. Tôi có thể triển khai trang web lên Netlify nhưng không thể triển khai lên Gitlab Pages. Để dự án này có thể duy trì quy trình triển khai hiện tại, tôi sẽ tìm cách triển khai giao diện Hugo Docsy cho các trang Gitlab.
KẾT QUẢ DỰ ÁN CÓ MONG MUỐN – Một trang web về dự án được tinh giản, tích hợp tài liệu, tài liệu tham khảo về mã, hướng dẫn và tin tức. – Sách hướng dẫn người dùng được tái cấu trúc và xem xét, phân tách nội dung dành cho người dùng và nhà phát triển, đồng thời bổ sung thông tin còn thiếu trước đó. – Quy trình hướng dẫn từ các ví dụ hiện có về tài liệu hướng dẫn, câu hỏi thường gặp và các vấn đề thường gặp.
CÔNG CỤ DỰ ÁN Tài liệu hiện tại của Allpix Squared sử dụng LaTeX, Doxygen, pandoc và Hugo, ngoài GitLab và Gitlab CI. Tôi và các cố vấn dự án đã trò chuyện về khả năng di chuyển nội dung từ LaTeX sang Markdown bằng các trình bổ trợ MathJax. Nếu thành công, quy trình làm việc của tài liệu sẽ liên quan đến Hugo, Markdown, Doxygen, git và Gitlab CI. Để giữ các hướng dẫn trong cùng một trang web/nền tảng, tôi sẽ sử dụng Hugo và Markdown. Tôi muốn tìm hiểu khả năng sử dụng Lớp học lập trình dưới dạng công cụ (ClaaT) cho các hướng dẫn. Vào tháng 7 này, tôi hy vọng có thể thử nghiệm quy trình làm việc ClaaT-Hugo và thảo luận về quy trình này với các cố vấn, nếu được chọn.
THỜI LƯỢNG DỰ ÁN Tôi yêu cầu hoàn tất dự án Allpix Squared trong khoảng thời gian 3 tháng tiêu chuẩn (từ ngày 14 tháng 9 năm 2020 đến ngày 30 tháng 11 năm 2020). Trong khoảng thời gian này, tôi sẽ dành khoảng 15 giờ mỗi tuần cho dự án này. Những giờ này sẽ bao gồm các cuộc họp cố vấn và email liên quan khi cần. Tôi cũng sẽ tuân thủ tiến trình của GSoD để gắn kết cộng đồng và hoàn thiện dự án.
NHIỆM VỤ DỰ ÁN Dưới đây là cách tôi dự định triển khai các nội dung cập nhật đề xuất cho bộ tài liệu Allpix Squared hiện có: 1. Nghiên cứu, thảo luận và khám phá các lựa chọn (từ ngày 17 tháng 8 đến ngày 13 tháng 9 năm 2020): – Tìm hiểu các yêu cầu của dự án – Cài đặt phần mềm Allpix Squared để xác định thông tin còn thiếu (nếu có) trong tài liệu hiện tại. – Yêu cầu thông tin xác thực cần thiết. – Tạo quy trình công việc của người dùng cho những người dùng khác nhau của Allpix Squared – Phân loại nội dung theo vai trò của người dùng – Kiểm tra tác động của việc chuyển đổi các tệp LaTeX sang Markdown – Hợp nhất các kho lưu trữ nguồn hoặc hiểu cách làm việc với nhiều kho lưu trữ git – Thêm vào đó: Thử nghiệm CLaaT dưới dạng một lựa chọn cho các video hướng dẫn – Phần thưởng: Thêm một tài liệu hướng dẫn định kiểu nhanh cho cộng đồng/tài liệu tham khảo mã ngắn để giúp duy trì cộng tác viên trong tài liệu
Tái cấu trúc, xem xét và nâng cao nội dung (14/9 – 19/10/2020): 2 nhiệm vụ mỗi tuần, mỗi nhiệm vụ mất khoảng 5-7 giờ. Tiến trình này có một tuần đệm để xử lý tình trạng chậm trễ hoặc các vấn đề không mong muốn.
- Xem xét nội dung hiện có và cách phân loại người dùng, đồng thời lưu ý đến quy trình làm việc của người dùng
- Lập dàn ý và kiểm thử quy trình công việc của nội dung được tái cấu trúc cho nhiều người dùng
- Tìm nguồn và cải thiện nội dung còn thiếu
- Chuyển đổi tệp LaTeX sang Markdown
- Hoàn thiện mục lục hướng dẫn người dùng và hướng dẫn nhà phát triển
- Tạo tệp PDF của hướng dẫn dành cho người dùng và nhà phát triển
- Bật mí thêm cho bạn: Xây dựng cấu trúc nội dung cho video hướng dẫn dựa trên các ví dụ và vấn đề
- Phần thưởng: Thiết lập quy trình làm việc của hướng dẫn cho các ví dụ về cách thực hiện Tiến trình: 5 tuần (Giai đoạn phát triển tài liệu)
Xây dựng trang web (từ ngày 19 tháng 10 đến ngày 30 tháng 11 năm 2020): 1-2 nhiệm vụ mỗi tuần, mỗi nhiệm vụ mất khoảng 5-7 giờ. Tiến trình này có một tuần đệm để khắc phục vấn đề và tinh chỉnh kết quả cuối cùng.
- Tìm hiểu và kiểm thử quy trình phát hành
- Xây dựng cấu trúc trang web bằng Hugo và Docsy
- Kiểm thử cách duy trì quy trình triển khai và quy trình làm việc tự động hiện tại bằng Docsy
- Lấy nội dung từ Doxygen
- Phát triển hướng dẫn sử dụng, hướng dẫn dành cho nhà phát triển và hướng dẫn từ nội dung LaTex hoặc Markdown
- Hoàn thiện giao diện của trang web dự án (biểu trưng, màu sắc, mẫu, bố cục, đường liên kết, khả năng hữu dụng và Gitlab CI/CD) Tiến trình: 6 tuần (Giai đoạn phát triển tài liệu)