หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิ Linux
- ผู้เขียนด้านเทคนิค:
- โบรอน
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารการโฮสต์และการสร้าง รวมถึงหน้าเริ่มต้นใช้งานและคู่มือนักพัฒนาซอฟต์แวร์ใหม่
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ :
เอกสารประกอบออกแบบมาเพื่อช่วยเหลือผู้ใช้ปลายทางและนักพัฒนาแอปในการใช้ผลิตภัณฑ์หรือบริการ เอกสารประกอบที่ดีนั้นสำคัญมาก เพราะเป็นช่องทางให้ผู้ใช้ได้เรียนรู้วิธีใช้ซอฟต์แวร์ รวมถึงฟีเจอร์ต่างๆ กลเม็ดเคล็ดลับ และแก้ไขปัญหาทั่วไปที่พบเมื่อใช้ซอฟต์แวร์ นอกจากนี้ ยังลดต้นทุนการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์องค์กรและโอเพนซอร์สของผลิตภัณฑ์ เอกสารที่ดีคือสัญญาณที่แสดงถึงประสิทธิภาพของผลิตภัณฑ์และทีมนักพัฒนาซอฟต์แวร์
หากไม่มีเอกสารที่ดี ผู้ใช้อาจไม่รู้วิธีทำสิ่งต่างๆ ข้างต้นได้อย่างมีประสิทธิภาพและประสิทธิผล เอกสารประกอบอาจมีบทบาทสำคัญในการรับประกันความสำเร็จของผลิตภัณฑ์ เนื่องจากการสื่อสารที่ยอดเยี่ยมจะเป็นหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์เสมอ เอกสารประกอบที่ดีเพียงแค่นำการสื่อสารนั้นมาใส่ไว้ในกรอบการทำงานที่จัดการได้ ซึ่งทุกคนจะเข้าถึงเพื่อความสำเร็จได้
เว็บไซต์เอกสารประกอบทุกเว็บไซต์ต้องมีการสร้างและโฮสต์ไปป์ไลน์ของเวิร์กโฟลว์ที่ดี สำหรับองค์กรอย่าง AGL ซึ่งมีหลายเวอร์ชันและมีเอกสารประกอบที่ละเอียดมากมาย ไฟล์เอกสาร (มาร์กดาวน์) จะกระจายไปทั่วที่เก็บหลายแหล่ง ทำให้งานดูแลรักษาและอัปเดตไฟล์ดังกล่าวมีความซับซ้อนมากและใช้เวลามาก
สถานะปัจจุบัน :
- เว็บไซต์เอกสาร AGL อิงตามคอลเล็กชันของไฟล์มาร์กดาวน์ที่ดึงมาจากที่เก็บหลายแห่ง
- ขณะนี้หน้าเอกสารจะโฮสต์ภายในแต่ละแหล่งที่มาเป็นมาร์กดาวน์โดยใช้เครื่องมือของโครงการ Cordova
- ซึ่งนำไปสู่การตั้งค่าที่เก็บ 4 แบบสำหรับการสร้างเอกสารประกอบและกระบวนการโฮสต์ ดังนี้
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : มีเทมเพลตเว็บไซต์ Jekyll
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : มีเครื่องมือในการสร้างเว็บไซต์ทางเทคนิคโดยอัตโนมัติจากไฟล์ Markdown
- แหล่งที่มาของเอกสาร [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 ที่ทำให้ใช้งานได้สำหรับเว็บไซต์เอกสารประกอบ [https://gist.github.com/growupboron/docs.automotivelinux.org]
- เครื่องมือ (สคริปต์) ที่มีอยู่ใน docs-tools [https://github.com/automotive-grade-linux/docs-tools] จะดูแลการรวบรวมและเทมเพลตไฟล์มาร์กดาวน์ทั้งหมดตาม 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 ทั้งหมดที่ไปยังไฟล์มาร์กดาวน์จากที่เก็บระยะไกล
- ทันทีที่ดึงไฟล์มาร์กดาวน์ทั้งหมด กระบวนการของเครื่องมือในการสร้างเว็บไซต์เอกสาร AGL ใน docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] ซึ่งจะมีการทำให้ใช้งานได้อย่างสอดคล้องกัน
- กระบวนการดูแลไปป์ไลน์ในปัจจุบันไม่เหมาะสำหรับผู้ใช้และนักพัฒนาแอป โดยเฉพาะอย่างยิ่งกับผู้ร่วมให้ข้อมูลรายใหม่ ไปป์ไลน์ของเวิร์กโฟลว์ (การสร้างและโฮสติ้ง) นี้เป็นวิธีที่ง่ายและมีประสิทธิภาพมากขึ้นสำหรับนักพัฒนาซอฟต์แวร์ในการมุ่งเน้นที่ส่วนเอกสารประกอบ แทนที่จะคงการสร้างเอกสารประกอบและเวิร์กโฟลว์การทำให้ใช้งานได้