หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- CERN-HSF
- ผู้เขียนด้านเทคนิค:
- SabitaR
- ชื่อโปรเจ็กต์:
- การปรับโครงสร้างและการปรับปรุงเอกสารของ Allpix Squared
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ภาพรวม ฉันได้เลือกโครงการ Allpix Squared ของ CERN-HSF ด้วยเหตุผลหลัก 2 ประการ ได้แก่
การสร้างทักษะ: เอกสารที่มีอยู่ของโปรเจ็กต์นี้มีความครอบคลุมและผสานรวมเนื้อหาหลายรูปแบบ การตรวจสอบและการปรับโครงสร้างชุดเอกสารที่ครอบคลุมนี้ใหม่จะช่วยฉันพัฒนาทักษะด้านการเขียนและสถาปัตยกรรมของข้อมูล นอกจากนี้ โดเมนโปรเจ็กต์ (ฟิสิกส์อนุภาค) ยังเป็นโดเมนใหม่สำหรับฉัน ผมจะต้องฝึกฝนทักษะการโต้ตอบของนักพัฒนาซอฟต์แวร์ ฉันเชื่อว่านักเขียนด้านเทคนิคสามารถประมวลผลข้อมูลจากนักพัฒนาซอฟต์แวร์และนำเสนอเนื้อหาที่เป็นประโยชน์สำหรับผู้ใช้ระดับใดก็ได้ หากเราได้ทำการค้นคว้าข้อมูลภูมิหลังที่จำเป็นและถามคำถามที่เหมาะสมแล้ว โครงงานนี้จะให้ฉันทดสอบทฤษฎีนี้
ความรู้ทางเทคนิค: โครงการนี้ต้องใช้ Hugo ซึ่งเป็นเครื่องมือที่รวมอยู่ที่ด้านบนของรายการเพื่อเรียนรู้ เราหวังว่าจะได้เรียนรู้เกี่ยวกับเวิร์กโฟลว์ LaTeX-Markdown-Hugo-GitLab-CI
ในระหว่างช่วงการสำรวจนักเขียนด้านเทคนิค ฉันได้พูดคุยกับที่ปรึกษาโปรเจ็กต์คร่าวๆ และทำความคุ้นเคยกับโครงสร้างชุดเอกสารที่มีอยู่ และได้สร้างเว็บไซต์สาธิต (https://ap2-demo.netlify.app/) เพื่อทดสอบว่าสามารถกำหนดค่า Hugo และ Docsy ในเครื่อง Windows ได้อย่างถูกต้องไหม ฉันสามารถทำให้เว็บไซต์ใช้งานได้ใน Netlify แต่ไม่ใช่ในหน้า Gitlab ฉันจะหาวิธีทำให้ธีม Hugo Docsy ใช้งานได้กับหน้า Gitlab เพื่อให้โปรเจ็กต์นี้คงเวิร์กโฟลว์การทำให้ใช้งานได้ในปัจจุบันไว้
ผลลัพธ์โครงการที่คาดหวัง - เว็บไซต์โครงการที่มีประสิทธิภาพ ซึ่งรวมเอกสารประกอบ การอ้างอิงโค้ด บทแนะนำ และข่าวสาร - คู่มือผู้ใช้ที่มีการปรับโครงสร้างและได้รับการตรวจสอบ ซึ่งแยกเนื้อหาสำหรับผู้ใช้และนักพัฒนาซอฟต์แวร์ออกจากกัน และมีข้อมูลที่ขาดหายไปก่อนหน้านี้ - ขั้นตอนการทำบทแนะนำจากตัวอย่างเอกสารแสดงวิธีการ คำถามที่พบบ่อย และปัญหาที่พบบ่อย
เครื่องมือของโครงการ เอกสารปัจจุบันของ Allpix Squared ใช้ LaTeX, Doxygen, pandoc และ Hugo นอกเหนือจาก GitLab และ Gitlab CI เรากับที่ปรึกษาของโครงการและได้คุยกันเกี่ยวกับการย้ายเนื้อหาจาก LaTeX ไปยัง Markdown ด้วยปลั๊กอิน MathJax ถ้าฉันทำสำเร็จ เวิร์กโฟลว์ของเอกสารจะเกี่ยวข้องกับ Hugo, Markdown, Doxygen, git และ Gitlab CI ผมจะใช้ Hugo และ Markdown เพื่อทำให้บทแนะนำอยู่ในเว็บไซต์/แพลตฟอร์มเดียวกัน ฉันอยากทราบถึงความเป็นไปได้ในการใช้ Codelabs-as-a-Tool (ClaaT) สำหรับบทแนะนำ ในเดือนกรกฎาคมนี้ ฉันหวังว่าจะได้ทดสอบเวิร์กโฟลว์ ClaaT-Hugo และพูดคุยกับ Mentor (หากได้รับเลือก)
ระยะเวลาของโครงการ เราจะขอทำโครงการ Allpix Squared ให้เสร็จสมบูรณ์ภายในระยะเวลามาตรฐาน 3 เดือน (14 ก.ย. 2020 - 30 พ.ย. 2020) ซึ่งในระหว่างนี้เราจะใช้เวลาประมาณ 15 ชั่วโมงต่อสัปดาห์ เวลาทำการเหล่านี้จะรวมการประชุมที่ปรึกษาและอีเมลที่เกี่ยวข้องตามที่จำเป็น ฉันจะปฏิบัติตามลำดับเวลาของ GSoD สำหรับการเชื่อมโยงชุมชนและการสรุปโปรเจ็กต์ด้วย
งานโครงการ นี่คือวิธีที่ฉันตั้งใจจะใช้การอัปเดตที่ฉันเสนอสำหรับชุดเอกสาร Allpix Squared ที่มีอยู่: 1. ค้นคว้า พูดคุย และสำรวจตัวเลือกต่างๆ (17 ส.ค. - 13 ก.ย. 2020): - ทำความเข้าใจข้อกำหนดของโปรเจ็กต์ - ติดตั้งซอฟต์แวร์ Allpix Squared เพื่อระบุข้อมูลที่ขาดหายไป (หากมี) ในเอกสารปัจจุบัน - ขอข้อมูลรับรองที่จำเป็น - สร้างเวิร์กโฟลว์ของผู้ใช้สำหรับผู้ใช้ต่างๆ ของ Allpix Squared - จำแนกประเภทเนื้อหาตามบทบาทของผู้ใช้ - ตรวจสอบผลของการแปลงไฟล์ LaTeX เป็น Markdown - รวมที่เก็บซอร์สหรือทำความเข้าใจวิธีทำงานกับที่เก็บ Git หลายรายการ - โบนัส: ทดสอบ CLaaT เป็นตัวเลือกสำหรับบทแนะนำ - Bonus: เขียนคู่มือสำหรับความช่วยเหลือเรื่อง Timeline สำหรับจัดทำเนื้อหาแบบรวดเร็ว:
ปรับโครงสร้าง ตรวจสอบ และเพิ่มประสิทธิภาพเนื้อหา (14 ก.ย. - 19 ต.ค. 2020): 2 งานต่อสัปดาห์ ใช้เวลาประมาณ 5-7 ชั่วโมงต่องาน ไทม์ไลน์นี้รวมถึงสัปดาห์บัฟเฟอร์เพื่อจัดการกับความล่าช้าหรือปัญหาที่ไม่คาดคิด
- ตรวจสอบเนื้อหาและการแยกประเภทเนื้อหาที่มีอยู่โดยคำนึงถึงเวิร์กโฟลว์ของผู้ใช้
- เวิร์กโฟลว์ Outline และทดสอบเนื้อหาที่มีโครงสร้างสำหรับผู้ใช้กลุ่มต่างๆ
- ระบุแหล่งที่มาและปรับปรุงเนื้อหาที่ขาดหายไป
- แปลงไฟล์ LaTeX เป็น Markdown
- สรุปคู่มือผู้ใช้และสารบัญของคู่มือนักพัฒนาซอฟต์แวร์
- สร้างไฟล์ PDF ของคู่มือผู้ใช้และคู่มือนักพัฒนาซอฟต์แวร์
- โบนัส: วางโครงสร้างเนื้อหาสำหรับบทแนะนำจากตัวอย่างและปัญหา
- โบนัส: กำหนดเวิร์กโฟลว์บทแนะนำสำหรับตัวอย่างวิธีการ ไทม์ไลน์: 5 สัปดาห์ (ระยะการพัฒนาเอกสาร)
สร้างเว็บไซต์ (19 ต.ค. - 30 พ.ย. 2020): 1-2 งานต่อสัปดาห์ ใช้เวลาประมาณ 5-7 ชั่วโมงต่องาน ลำดับเวลานี้รวมถึงสัปดาห์บัฟเฟอร์เพื่อแก้ปัญหาและปรับแต่งผลลัพธ์สุดท้าย
- ทำความเข้าใจและทดสอบเวิร์กโฟลว์การเผยแพร่
- สร้างโครงสร้างเว็บไซต์โดยใช้ Hugo และ Docsy
- ทดสอบวิธีบำรุงรักษาการทำให้ใช้งานได้และเวิร์กโฟลว์อัตโนมัติในปัจจุบันด้วย Docs
- ดึงเนื้อหาจาก Doxygen
- พัฒนาคู่มือผู้ใช้ คู่มือนักพัฒนาซอฟต์แวร์ และบทแนะนำจากเนื้อหา LaTex หรือ Markdown
- ปรับแต่งรูปลักษณ์ของเว็บไซต์โปรเจ็กต์ (โลโก้ สี เทมเพลต เลย์เอาต์ ลิงก์ ความสามารถในการใช้งาน และ Gitlab CI/CD) ไทม์ไลน์: 6 สัปดาห์ (ระยะการพัฒนาเอกสาร)