หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- พื้นฐาน Linux
- นักเขียนเชิงเทคนิค
- boron
- ชื่อโปรเจ็กต์:
- ปรับปรุงโฮสติ้งและการสร้างเอกสารประกอบ รวมถึงปรับโครงสร้างหน้าเริ่มต้นใช้งานและคู่มือนักพัฒนาแอป
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ข้อมูลสรุป :
เอกสารประกอบออกแบบมาเพื่อช่วยเหลือผู้ใช้ปลายทางและนักพัฒนาซอฟต์แวร์ในการใช้ผลิตภัณฑ์หรือบริการ เอกสารประกอบที่ดีมีความสำคัญมากเนื่องจากเป็นช่องทางให้ผู้ใช้เรียนรู้วิธีใช้ซอฟต์แวร์ ฟีเจอร์ เคล็ดลับ และวิธีแก้ปัญหาที่พบได้ทั่วไปเมื่อใช้ซอฟต์แวร์ นอกจากนี้ยังลดต้นทุนการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์ขององค์กรและโอเพนซอร์สของผลิตภัณฑ์ เอกสารที่ดีเป็นสัญญาณที่แสดงถึงความสมบูรณ์ของผลิตภัณฑ์และทีมนักพัฒนา
หากไม่มีเอกสารประกอบที่ดี ผู้ใช้อาจไม่ทราบวิธีทําสิ่งต่างๆ ข้างต้นอย่างมีประสิทธิภาพ เอกสารประกอบมีบทบาทสําคัญในการช่วยให้ผลิตภัณฑ์ประสบความสําเร็จ เนื่องจากการสื่อสารที่ยอดเยี่ยมเป็นหัวใจสําคัญของธุรกิจหรือผลิตภัณฑ์เสมอมา และเอกสารประกอบที่ยอดเยี่ยมก็นําการสื่อสารนั้นมาใส่ไว้ในเฟรมเวิร์กที่สามารถจัดการได้ ซึ่งทุกคนสามารถเข้าถึงเพื่อช่วยให้ประสบความสําเร็จ
เว็บไซต์เอกสารประกอบทุกแห่งต้องมีเวิร์กโฟลว์การสร้างและโฮสติ้งที่ดี ในองค์กรอย่าง AGL ที่มีเอกสารประกอบหลายเวอร์ชันและรายละเอียดมากมาย ไฟล์เอกสารประกอบ (Markdown) จะกระจายอยู่ในที่เก็บข้อมูลหลายแห่ง ทำให้การดูแลรักษาและการอัปเดตเอกสารประกอบมีความซับซ้อนและใช้เวลาอย่างมาก
สถานะปัจจุบัน :
- เว็บไซต์เอกสาร AGL นี้อิงกับคอลเล็กชันของไฟล์มาร์กดาวน์ที่ดึงมาจากที่เก็บต่างๆ
- ปัจจุบันหน้าเอกสารโฮสต์อยู่ภายในแหล่งที่มาแต่ละแหล่งเป็นมาร์กดาวน์โดยใช้เครื่องมือของโปรเจ็กต์ Cordoa
- ซึ่งจะนำไปสู่การตั้งค่าที่เก็บ 4 รายการสำหรับกระบวนการสร้างและโฮสต์เอกสารประกอบ ดังนี้
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : มีเทมเพลตเว็บไซต์ Jekyll
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : มีเครื่องมือในการสร้างเว็บไซต์ทางเทคนิคจากไฟล์ Markdown โดยอัตโนมัติ
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : แหล่งที่มา (markdowns [https://github.com/automotive-Grade-linux/docs-sources/tree/master/docs]) สำหรับเอกสารทั่วไปและคำแนะนำ
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : เผยแพร่ที่เก็บ GitHub Pages สำหรับเว็บไซต์เอกสารประกอบ [https://gist.github.com/growupboron/docs.automotivelinux.org]
- เครื่องมือ (สคริปต์) ที่มีอยู่ใน docs-tools [https://github.com/automotive-grade-linux/docs-tools] จะจัดการรวบรวมและสร้างเทมเพลตไฟล์ Markdown ทั้งหมดตาม fetched_files.yml ซึ่งอยู่ใน docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]
- เวิร์กโฟลว์ปัจจุบันของการสร้างเว็บไซต์เอกสารประกอบ agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml มีลิงก์ไปยังไฟล์ yaml ของหนังสือทั้งหมด จากนั้นจะดึงข้อมูลไฟล์ yaml ของหนังสือทั้งหมดจากที่เก็บระยะไกลไปยัง docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] ไฟล์ yaml ของหนังสือจะมี URL ทั้งหมดไปยังไฟล์ Markdown จากที่เก็บข้อมูลระยะไกล
- ทันทีที่ดึงไฟล์มาร์กดาวน์ทั้งหมด กระบวนการของเครื่องมือสร้างเว็บไซต์เอกสาร AGL ในหน้า docs-gh-pages [https://github.com/automotive-อาจจะ-linux/docs-gh-pages] ซึ่งจะมีการนำไปใช้อย่างเหมาะสม
- กระบวนการดูแลไปป์ไลน์ในปัจจุบันไม่เหมาะกับผู้ใช้และนักพัฒนาแอป โดยเฉพาะกับผู้ร่วมให้ข้อมูลรายใหม่ ไปป์ไลน์เวิร์กโฟลว์นี้ (การสร้างและโฮสติ้ง) สามารถลดความซับซ้อนและปรับปรุงให้มีประสิทธิภาพมากขึ้นเพื่อให้นักพัฒนาแอปมุ่งเน้นที่ส่วนเอกสารประกอบแทนที่จะต้องดูแลเวิร์กโฟลว์การสร้างและทำให้ใช้งานได้