หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- The Linux Foundation
- นักเขียนเชิงเทคนิค:
- boron
- ชื่อโปรเจ็กต์:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (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] : มีเครื่องมือสำหรับสร้างเว็บไซต์ทางเทคนิคจากไฟล์มาร์กดาวน์โดยอัตโนมัติ
- Docs-sources [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 Pages ที่ใช้งานจริงสำหรับเว็บไซต์เอกสารประกอบ [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] ซึ่งจะใช้งานจริงตามนั้น
- กระบวนการปัจจุบันในการดูแลรักษาไปป์ไลน์ไม่สะดวกสำหรับผู้ใช้และนักพัฒนาซอฟต์แวร์ โดยเฉพาะอย่างยิ่งผู้มีส่วนร่วมรายใหม่ ไปป์ไลน์เวิร์กโฟลว์นี้ (การสร้างและการโฮสต์) สามารถทำให้ง่ายขึ้นและมีประสิทธิภาพมากขึ้น เพื่อให้นักพัฒนาซอฟต์แวร์มุ่งเน้นไปที่ส่วนเอกสารประกอบแทนที่จะดูแลรักษาเวิร์กโฟลว์การสร้างและการใช้งานเอกสารประกอบ