หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- VideoLAN
- นักเขียนเชิงเทคนิค:
- Edidiong Anny Asikpo
- ชื่อโปรเจ็กต์:
- ปรับปรุง (เขียนใหม่) เอกสารประกอบสำหรับผู้ใช้ VLC ให้ทันสมัย
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ABSTRACT
เอกสารประกอบสำหรับผู้ใช้ออกแบบมาเพื่อช่วยผู้ใช้ปลายทางในการใช้ผลิตภัณฑ์หรือบริการ เอกสารประกอบที่เป็นประโยชน์สําหรับผู้ใช้มีความสําคัญมาก เนื่องจากเป็นช่องทางให้ผู้ใช้เรียนรู้วิธีใช้ซอฟต์แวร์ ฟีเจอร์ เคล็ดลับ และวิธีแก้ปัญหาที่พบได้ทั่วไปเมื่อใช้ซอฟต์แวร์ นอกจากนี้ ยังช่วยลดค่าใช้จ่ายในการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์ขององค์กรสำหรับผลิตภัณฑ์ด้วย เอกสารประกอบที่เป็นประโยชน์สำหรับผู้ใช้เป็นสัญญาณบ่งชี้ว่าผลิตภัณฑ์ทำงานได้อย่างถูกต้อง ทีมนักพัฒนาซอฟต์แวร์
หากไม่มีเอกสารประกอบที่เป็นประโยชน์สำหรับผู้ใช้ ผู้ใช้อาจไม่ทราบวิธีดำเนินการข้างต้นอย่างมีประสิทธิภาพ เอกสารสำหรับผู้ใช้จะมีบทบาทสำคัญในการสร้างความสำเร็จของผลิตภัณฑ์ เนื่องจากการสื่อสารที่ดีคือหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์นั้นๆ เสมอ และเอกสารประกอบที่ดีคือการนำการสื่อสารนั้นมาไว้ในกรอบการทำงานที่จัดการได้ ซึ่งทุกคนสามารถเข้าถึงเพื่อความสำเร็จ
ขณะเขียนบทความนี้ เอกสารประกอบสำหรับผู้ใช้ VLC มีการเข้าถึง 4,634,065 ครั้ง และมีเดียเพลเยอร์ VLC มีการดาวน์โหลดประมาณ 23 ล้านครั้งทุกเดือนจากเว็บไซต์หลัก ซึ่งแสดงให้เห็นว่าผู้คนจำนวนมากทั่วโลกใช้ VLC Media Player และอาจต้องการอ่านเอกสารประกอบสำหรับผู้ใช้เพื่อดูคำแนะนำเกี่ยวกับวิธีใช้มีเดียเพลเยอร์ อย่างไรก็ตาม ขณะนี้เอกสารประกอบสำหรับผู้ใช้ของ VLC Media Player ล้าสมัยและไม่สมบูรณ์ (แก้ไขล่าสุดเมื่อวันที่ 28 ตุลาคม 2015) และชุมชน VideoLAN ต้องการใช้โปรเจ็กต์นี้เพื่อปรับปรุงเอกสารประกอบสำหรับผู้ใช้เพื่อให้ผู้ใช้ปลายทางได้รับประสบการณ์การใช้งานที่ราบรื่นเมื่อใช้ VLC Media Player
สถานะปัจจุบัน
ขณะนี้เอกสารประกอบสำหรับผู้ใช้มีอยู่ในหน้า Wiki เนื้อหาล้าสมัย ไม่สมบูรณ์ นำทางได้ยากหรือค้นหาข้อมูลได้ยาก ไม่ครอบคลุมข้อมูลเกี่ยวกับมีเดียเพลเยอร์เวอร์ชันปัจจุบัน และสามารถแปลได้เฉพาะในภาษาเยอรมันเท่านั้น ซึ่งก่อให้เกิดความสูญเสียครั้งใหญ่สำหรับผู้ที่ไม่สามารถอ่านภาษาอังกฤษ
เหตุใดเอกสารประกอบสำหรับผู้ใช้ที่ฉันเสนอจึงดีกว่าเอกสารประกอบที่มีอยู่
เอกสารประกอบสำหรับผู้ใช้ที่เสนอจะมีโครงสร้างเพื่อปรับปรุงและรับประกันประสิทธิภาพ ความสอดคล้อง และความสบายใจให้แก่ผู้ใช้ปลายทาง โดยจะมีคู่มือแบบเขียนและรูปภาพที่เกี่ยวข้อง รวมถึงวิธีการและคำอธิบายเกี่ยวกับวิธีใช้ฟีเจอร์แต่ละอย่างของโปรแกรมเล่นสื่อ VLC เป็นข้อมูลล่าสุด ใช้งานง่าย เข้าใจง่าย และแปลเป็นภาษาหลักอย่างน้อย 5 ภาษา
ที่ปรึกษา: Jean-Baptiste, Alex, Simon
การวิเคราะห์
Jean-Baptiste และฉันได้พูดคุยกันเกี่ยวกับสภาพแวดล้อมใหม่ที่จะย้ายข้อมูลเอกสารประกอบสำหรับผู้ใช้ในปัจจุบันเพื่อปรับปรุง และเขาแชร์ลิงก์ 2 ลิงก์ที่แสดงที่เก็บ Gitlab ของไฟล์ต้นฉบับที่เขียนด้วย Sphinx และเอกสารประกอบหลักที่โฮสต์ใน Read the Docs และเขาบอกว่าคาดว่าเอกสารประกอบใหม่จะคล้ายกับเอกสารประกอบดังกล่าว เราได้ค้นคว้าข้อมูลเกี่ยวกับเครื่องมือเหล่านี้อย่างละเอียดเพื่อให้เข้าใจวิธีการทำงานของเครื่องมือมากขึ้น
สฟิงซ์
Sphinx เป็นโซลูชันที่มีประสิทธิภาพและใช้งานได้จริงสำหรับเอกสารประกอบซอฟต์แวร์ ซึ่งประกอบด้วยฟีเจอร์หลายอย่างที่นักเขียนต้องการ เช่น การเผยแพร่จากแหล่งที่มาเดียว การนำเนื้อหามาใช้ซ้ำผ่านการรวม การรวมแบบมีเงื่อนไขตามประเภทเนื้อหาและแท็ก ธีม HTML ที่ใช้งานจริงหลายธีมซึ่งมอบประสบการณ์การใช้งานที่ยอดเยี่ยมบนอุปกรณ์เคลื่อนที่และเดสก์ท็อป การอ้างอิงในหน้าเว็บ เอกสาร และโปรเจ็กต์ต่างๆ การรองรับดัชนีและอภิธานศัพท์ รวมถึงการรองรับหลายภาษา นอกจากนี้ ยังใช้ reStructuredText เป็นภาษามาร์กอัปด้วย จุดแข็งหลายอย่างมาจากความสามารถที่มีประสิทธิภาพและตรงไปตรงมาของ reStructuredText รวมถึงความสามารถในการแปลเอกสารประกอบ
อ่านเอกสาร
Read the Docs ช่วยให้เอกสารประกอบของซอฟต์แวร์เป็นเรื่องง่ายขึ้นด้วยการสร้าง การจัดเวอร์ชัน และการโฮสต์เอกสารให้คุณโดยอัตโนมัติ เบราว์เซอร์จะไม่ซิงค์กัน กล่าวคือ เมื่อใดก็ตามที่คุณพุชโค้ดไปยังระบบควบคุมเวอร์ชันที่คุณชื่นชอบ ไม่ว่าจะเป็น Git, Mercurial, Bazaar หรือ Subversion อ่านเอกสารจะสร้างเอกสารโดยอัตโนมัติ ดังนั้นโค้ดและเอกสารประกอบของคุณเป็นปัจจุบันอยู่เสมอ เอกสารนี้มีด้วยกันหลายเวอร์ชัน อ่านเอกสารสามารถโฮสต์และสร้างเอกสารหลายเวอร์ชันได้ ดังนั้นการมีเอกสารเวอร์ชัน 1.0 และเอกสารเวอร์ชัน 2.0 จึงง่ายพอๆ กับการมีสาขาหรือแท็กแยกต่างหากในระบบควบคุมเวอร์ชันของคุณ Read the Docs เป็นซอฟต์แวร์โอเพนซอร์สที่ไม่มีค่าใช้จ่ายและโฮสต์เอกสารประกอบสำหรับโปรเจ็กต์โอเพนซอร์สขนาดใหญ่และขนาดเล็กเกือบ 100,000 โปรเจ็กต์ในภาษาต่างๆ เกือบทุกภาษา
ผลการตรวจสอบ
Sphinx เป็นเครื่องมือที่มีประสิทธิภาพอย่างเหลือเชื่อ และ Read the Docs สร้างขึ้นเพื่อให้บริการโฮสติ้งสำหรับเอกสารประกอบของ Sphinx ซึ่งทำให้เอกสารของคุณเป็นเวอร์ชันล่าสุดอยู่เสมอ เครื่องมือเหล่านี้เป็นชุดเครื่องมือที่ยอดเยี่ยมที่นักพัฒนาซอฟต์แวร์และผู้เขียนเนื้อหาทางเทคนิคสามารถใช้เพื่อสร้างเอกสารประกอบสำหรับผู้ใช้ซึ่งเหมาะกับผู้ใช้ปลายทางมากที่สุด
Sphinx รองรับการแปลเอกสารเป็นหลายภาษา โดยรองรับการควบคุมเวอร์ชันที่จะใช้ในการจัดการเอกสารประกอบ ซึ่งแตกต่างจากวิกิปัจจุบันที่ทุกคนแก้ไขได้และอาจไม่ได้เพิ่มข้อมูลที่ถูกต้อง แต่ระบบควบคุมเวอร์ชันนี้จะตรวจสอบการเปลี่ยนแปลงทั้งหมดก่อนผสานเข้ากับที่เก็บข้อมูลหลัก การควบคุมเวอร์ชันยังทำให้เอกสารประกอบมีเนื้อหาที่มาจากโอเพนซอร์สมากขึ้นในโปรเจ็กต์ด้วย เนื่องจากผู้ใช้สามารถสร้างปัญหา เปิดคำขอดึงข้อมูล ฯลฯ ชุมชนและโครงการอื่นๆ อีกมากมายใช้ Sphinx และ Read the Docs เช่น ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs เป็นต้น และเครื่องมือเหล่านี้เป็นเครื่องมือที่ยอดเยี่ยมสำหรับเอกสารประกอบผู้ใช้ VLC เวอร์ชันใหม่
เราไม่ได้แค่อ่านเกี่ยวกับเครื่องมือเหล่านี้ แต่ยังสร้างตัวอย่างพื้นฐานด้วย ลิงก์ไปยังที่เก็บ Gitlab ของฉันคือ https://gitlab.com/Didicodes/demo-vlc-user-documentation ส่วนเวอร์ชันที่โฮสต์บน readthedocs อยู่ที่นี่ [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/
โครงสร้างของเอกสารที่นำเสนอ
ฉันได้สร้างโครงสร้างสำหรับเอกสารประกอบผู้ใช้ VLC แล้ว ซึ่งดูได้ที่ https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing โครงสร้างใหม่นี้ต้องได้รับการอนุมัติจากพี่เลี้ยงก่อนจึงจะเริ่มใช้งานได้ ซึ่งหมายความว่าโครงสร้างมีแนวโน้มที่จะเปลี่ยนแปลงหลังจากได้รับการตรวจสอบโดยที่ปรึกษาแล้ว
เป้าหมายโปรเจ็กต์
- ปรับโครงสร้างเอกสารประกอบ
- อัปเดตเอกสารประกอบให้เหมาะกับ VLC เวอร์ชันปัจจุบัน
- ย้ายข้อมูลเอกสารประกอบสำหรับผู้ใช้ไปยัง Gitlab โดยใช้ Sphinx และ ReadtheDocuments
- นำรูปภาพและข้อมูลที่ล้าสมัยออก
- เขียนเอกสารประกอบสำหรับผู้ใช้ใหม่เพื่อให้เข้าใจได้ง่ายขึ้น
- ตั้งค่าให้แปลโดยใช้ Sphinx Internationalization
- จัดทำเอกสารประกอบโดยคำนึงถึงชุมชนเพื่อให้ผู้ใช้รายงานหรือแก้ปัญหาที่พบขณะอ่านเอกสารประกอบได้
เหตุผลที่เลือกโปรเจ็กต์นี้
เราเชื่อมั่นมาตลอดว่าการเขียนโค้ด การแก้ปัญหา และการสร้างซอฟต์แวร์จะมีประสิทธิภาพสูงสุดเมื่อคุณมีความสามารถในการชี้แนะผู้อื่นเกี่ยวกับเรื่องนี้ผ่านการเขียน เราประทับใจในความพยายามของชุมชน VideoLAN ในการสร้างโซลูชันซอฟต์แวร์ฟรีสำหรับมัลติมีเดียมาโดยตลอด ตั้งแต่เด็ก เราใช้ VLC Media Player เป็นซอฟต์แวร์ในการฟังเพลงหรือดูภาพยนตร์เสมอ เนื่องจากเสียงดังมากและมีฟีเจอร์มากมาย ฉันรู้สึกเป็นเกียรติอย่างยิ่งที่ได้ทำงานร่วมกับชุมชนที่ช่วยกันทำให้ชีวิตตอนเด็กๆ ของฉันน่าประทับใจ
ทำไมฉันถึงเป็นบุคคลที่เหมาะสมสำหรับโปรเจ็กต์นี้
ฉันเชื่อว่าเราคือผู้ที่รับผิดชอบโปรเจ็กต์นี้ เนื่องจากสาเหตุต่อไปนี้
- ฉันมีประสบการณ์ที่ผ่านมาในการปรับปรุงเอกสารประกอบขององค์กรและสามารถใช้ระบบควบคุมเวอร์ชันใดก็ได้ ดังนั้นการดำเนินการตามคำสั่งใน Gitab จึงไม่ใช่ปัญหา นอกจากนี้ สิ่งที่กระตุ้นให้ฉันทำงานคือการทำงานในโปรเจ็กต์ที่สร้างคุณค่าให้กับผู้คน
- เราเชื่อว่าหากต้องการให้ผู้อื่นทําสิ่งใดสิ่งหนึ่งอย่างมีประสิทธิภาพสูงสุด คุณควรบันทึกไว้ การบันทึกกระบวนการจะช่วยให้ทุกคนที่เกี่ยวข้องทำงานได้อย่างมีประสิทธิภาพ สอดคล้องกัน และวางใจได้
- เราทราบดีถึงความต้องการของผู้ใช้ VLC เพราะเราก็เป็นหนึ่งในผู้ใช้เหล่านั้น ซึ่งจะช่วยให้เขียนเอกสารประกอบได้ในลักษณะที่ทำให้ผู้ใช้ทุกคนทั่วโลกเข้าใจได้ในครั้งแรก