หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- 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 Pages
ผลลัพธ์โครงการที่คาดว่าจะเกิดขึ้น - เว็บไซต์ของโครงการที่ได้รับการปรับปรุงให้มีประสิทธิภาพมากขึ้น โดยรวมเอกสารประกอบ ข้อมูลอ้างอิงโค้ด บทแนะนำ และข่าวสารเข้าไว้ด้วยกัน - คู่มือผู้ใช้ที่จัดโครงสร้างใหม่และได้รับการตรวจสอบแล้ว ซึ่งจะแยกเนื้อหาสำหรับผู้ใช้และนักพัฒนาซอฟต์แวร์ออกจากกัน และมีข้อมูลที่ขาดหายไปก่อนหน้านี้ - เวิร์กโฟลว์ของบทแนะนำจากตัวอย่างเอกสารประกอบวิธีการ คำถามที่พบบ่อย และปัญหาที่พบได้ทั่วไป
เครื่องมือของโปรเจ็กต์ เอกสารประกอบปัจจุบันของ Allpix Squared ใช้ LaTeX, Doxygen, pandoc และ Hugo นอกเหนือจาก GitLab และ Gitlab CI ผมและที่ปรึกษาโปรเจ็กต์ได้พูดคุยกันเรื่องการย้ายเนื้อหาจาก LaTeX ไปเป็นมาร์กดาวน์โดยใช้ปลั๊กอิน MathJax หากดำเนินการสำเร็จ เวิร์กโฟลว์เอกสารจะเกี่ยวข้องกับ Hugo, Markdown, Doxygen, git และ Gitlab CI ถ้าจะเก็บบทแนะนำไว้ในเว็บไซต์/แพลตฟอร์มเดียวกัน ผมจะใช้ Hugo และ Markdown ฉันอยากทราบความเป็นไปได้ในการใช้ Codelabs เป็นเครื่องมือ (ClaaT) สำหรับบทแนะนำ ในเดือนกรกฎาคมนี้ เราหวังว่าจะได้ทดสอบเวิร์กโฟลว์ ClaaT-Hugo และพูดคุยกับพี่เลี้ยง หากได้รับเลือก
ระยะเวลาของโปรเจ็กต์ ฉันขอทำโปรเจ็กต์ Allpix Squared ให้เสร็จภายในระยะเวลามาตรฐาน 3 เดือน (14 กันยายน 2020 - 30 พฤศจิกายน 2020) ซึ่งฉันจะใช้เวลาประมาณ 15 ชั่วโมงต่อสัปดาห์ โดยชั่วโมงเหล่านี้จะรวมการประชุมกับที่ปรึกษาและอีเมลที่เกี่ยวข้องตามที่จำเป็น ฉันจะปฏิบัติตามลำดับเวลาของ GSoD สำหรับการสานสัมพันธ์ของชุมชนและการสรุปโปรเจ็กต์ด้วย
งานในโปรเจ็กต์ นี่คือวิธีที่ฉันตั้งใจจะนำการอัปเดตที่เสนอไปใช้กับชุดเอกสาร Allpix Squared ที่มีอยู่ 1. ค้นคว้า อภิปราย และสำรวจทางเลือกต่างๆ (17 ส.ค. - 13 ก.ย. 2020): - ทำความเข้าใจข้อกำหนดของโปรเจ็กต์ - ติดตั้งซอฟต์แวร์ Allpix Squared เพื่อระบุข้อมูลที่ขาดไป (หากมี) ในเอกสารปัจจุบัน - ขอข้อมูลเข้าสู่ระบบที่จำเป็น - สร้างเวิร์กโฟลว์ของผู้ใช้สำหรับผู้ใช้ที่แตกต่างกันของ Allpix Squared - จำแนกเนื้อหาตามบทบาทของผู้ใช้ - ตรวจสอบผลของการแปลงไฟล์ LaTeX เป็นมาร์กดาวน์ - รวมที่เก็บต้นทางหรือทำความเข้าใจวิธีทำงานกับที่เก็บ Git หลายรายการ - โบนัส: ทดสอบ CLaaT เพื่อเป็นตัวเลือกสำหรับบทแนะนำ - โบนัส: ช่วยผู้เขียนเอกสารอ้างอิงเฟส/Shorts
ปรับโครงสร้าง ตรวจสอบ และปรับปรุงเนื้อหา (14 ก.ย. - 19 ต.ค. 2020): งาน 2 รายการต่อสัปดาห์ โดยใช้เวลาประมาณ 5-7 ชั่วโมงต่องาน ลำดับเวลานี้รวมช่วงพักสัปดาห์หนึ่งไว้เพื่อจัดการกับความล่าช้าหรือปัญหาที่ไม่คาดคิด
- ตรวจสอบเนื้อหาที่มีอยู่และการจัดประเภทผู้ใช้โดยคำนึงถึงเวิร์กโฟลว์ของผู้ใช้
- ร่างและทดสอบเวิร์กโฟลว์เนื้อหาปรับโครงสร้างสำหรับผู้ใช้ที่ต่างกัน
- ค้นหาและปรับปรุงเนื้อหาที่ขาดหายไป
- แปลงไฟล์ LaTeX เป็นมาร์กดาวน์
- สรุปสารบัญของคู่มือผู้ใช้และคู่มือนักพัฒนาแอป
- สร้างไฟล์ PDF ของคู่มือผู้ใช้และคู่มือนักพัฒนาซอฟต์แวร์
- โบนัส: จัดโครงสร้างเนื้อหาสำหรับบทแนะนำจากตัวอย่างและปัญหา
- โบนัส: สร้างเวิร์กโฟลว์บทแนะนำสำหรับตัวอย่างวิธีการ ลำดับเวลา: 5 สัปดาห์ (ระยะการพัฒนาเอกสาร)
สร้างเว็บไซต์ (19 ต.ค. - 30 พ.ย. 2020): 1-2 งานต่อสัปดาห์ โดยใช้เวลาประมาณ 5-7 ชั่วโมงต่องาน ลำดับเวลานี้รวมช่วงพัก 1 สัปดาห์ไว้เพื่อแก้ปัญหาและปรับแต่งเอาต์พุตขั้นสุดท้าย
- ทำความเข้าใจและทดสอบเวิร์กโฟลว์การเผยแพร่
- สร้างโครงสร้างเว็บไซต์โดยใช้ Hugo และ Docsy
- ทดสอบวิธีการดูแลรักษาการติดตั้งใช้งานและเวิร์กโฟลว์อัตโนมัติในปัจจุบันโดยใช้ Docsy
- ดึงเนื้อหาจาก Doxygen
- พัฒนาคู่มือผู้ใช้ คู่มือนักพัฒนาแอป และบทแนะนำจากเนื้อหา LaTex หรือ Markdown
- ปรับแต่งรูปลักษณ์ของเว็บไซต์โครงการ (โลโก้ สี เทมเพลต เลย์เอาต์ ลิงก์ ความสามารถในการใช้งาน และ CI/CD ของ Gitlab) ลำดับเวลา: 6 สัปดาห์ (ระยะการพัฒนาเอกสาร)