หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิ Linux
- ผู้เขียนด้านเทคนิค:
- โบรอน
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบการโฮสต์ การสร้าง และการปรับโครงสร้างหน้าเริ่มต้นใช้งานและคู่มือนักพัฒนาซอฟต์แวร์
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
บทคัดย่อ :
เอกสารประกอบออกแบบมาเพื่อช่วยเหลือผู้ใช้ปลายทางและนักพัฒนาแอปในการใช้ผลิตภัณฑ์หรือบริการ เอกสารประกอบที่ดีเป็นสิ่งสำคัญอย่างยิ่ง เนื่องจากจะเปิดโอกาสให้ผู้ใช้ได้เรียนรู้วิธีใช้ซอฟต์แวร์ รวมถึงฟีเจอร์ต่างๆ เคล็ดลับ คำแนะนำต่างๆ และแก้ไขปัญหาทั่วไปที่พบขณะใช้งานซอฟต์แวร์ นอกจากนี้ ยังลดค่าใช้จ่ายในการสนับสนุน รวมถึงเป็นส่วนหนึ่งของเอกลักษณ์องค์กรและโอเพนซอร์สของผลิตภัณฑ์ เอกสารที่ดีจะบ่งชี้ถึงคุณภาพของผลิตภัณฑ์และทีมนักพัฒนาแอป
หากไม่มีเอกสารประกอบที่ดี ผู้ใช้อาจไม่ทราบวิธีทำสิ่งต่างๆ ข้างต้นได้อย่างมีประสิทธิภาพและประสิทธิผล เอกสารประกอบอาจมีบทบาทสำคัญในการสร้างความสําเร็จของผลิตภัณฑ์ เนื่องจากการสื่อสารที่ยอดเยี่ยมเป็นหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์เสมอ เอกสารประกอบที่ดีจะต้องนำการสื่อสารนั้นมาใส่ไว้ในกรอบการทำงานที่ทุกคนเข้าถึงได้ เพื่อให้ทุกคนเข้าถึงได้
เว็บไซต์เอกสารประกอบทุกเว็บไซต์ต้องมีการสร้างและโฮสต์เวิร์กโฟลว์ที่ดีในองค์กรอย่างเช่น AGL ที่มีหลายเวอร์ชันและเอกสารที่ซับซ้อนจำนวนมาก ไฟล์เอกสาร (มาร์กดาวน์) จะกระจายไปทั่วที่เก็บหลายแหล่ง ซึ่งทำให้งานดูแลรักษาและอัปเดตไฟล์เหล่านั้นมีความซับซ้อนมากและใช้เวลามาก
สถานะปัจจุบัน :
- เว็บไซต์เอกสาร AGL อิงตามคอลเล็กชันของไฟล์มาร์กดาวน์ที่ดึงมาจากที่เก็บหลายแห่ง
- ขณะนี้หน้าเอกสารจะโฮสต์อยู่ภายในแหล่งที่มาแต่ละรายการเป็นมาร์กดาวน์โดยใช้เครื่องมือของโปรเจ็กต์ Cordova
- ซึ่งจะทำให้เกิดการตั้งค่าที่เก็บ 4 รายการสำหรับกระบวนการสร้างและโฮสต์เอกสาร
- เทมเพลตเอกสาร-เว็บ [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] : ที่มา (มาร์กดาวน์ [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-เกรด-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] ซึ่งใช้งานได้
- กระบวนการในการดูแลรักษาไปป์ไลน์ในปัจจุบันไม่ได้เป็นมิตรกับผู้ใช้และนักพัฒนาซอฟต์แวร์ โดยเฉพาะกับผู้ร่วมให้ข้อมูลรายใหม่ ไปป์ไลน์ของเวิร์กโฟลว์ (การสร้างและโฮสติ้ง) นี้ใช้งานง่ายและมีประสิทธิภาพมากขึ้นสำหรับนักพัฒนาแอปในการให้ความสำคัญกับส่วนเอกสารประกอบ แทนที่จะคงขั้นตอนการสร้างเอกสารและการติดตั้งใช้งาน