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