หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- VLC
- นักเขียนเชิงเทคนิค
- Abhishek Pratap Singh
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบสำหรับผู้ใช้ VLC ให้ทันสมัยต่อไป
- ความยาวของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
สถานะปัจจุบันของเอกสารประกอบ
เอกสารประกอบสำหรับผู้ใช้ VLC กำลังอยู่ระหว่างการปรับปรุงและอัปเดต เรากําลังอยู่ระหว่างการเปลี่ยนจากเอกสารประกอบแบบเก่าที่ใช้ Wiki[1] ไปเป็นเอกสารประกอบสําหรับผู้ใช้สมัยใหม่ที่สร้างด้วย Sphinx[2] ซึ่งโฮสต์อยู่บน ReadTheDocs
กลุ่มเป้าหมาย
กลุ่มเป้าหมายเป็นทั้งผู้ใช้ที่สงสัยใคร่รู้ซึ่งต้องการสำรวจฟีเจอร์ต่างๆ ของมีเดียเพลเยอร์ VLC ที่นอกเหนือจากมีเดียเพลเยอร์ทั่วไป ซึ่งก็ช่วยนักพัฒนาซอฟต์แวร์ได้เป็นอย่างดีด้วยการเป็นคู่มืออ้างอิงที่ใช้งานง่าย เราจึงวางแผนที่จะใส่ทั้งวิธีการแบบ GUI (พร้อมรูปภาพที่เกี่ยวข้อง) และวิธีการแบบ CLI (พร้อมตัวอย่างโค้ด) เพื่อให้ผู้ใช้ปลายทางมีอิสระในการเลือก
เราเชื่อว่าภาษาของเอกสารประกอบ (โดยเฉพาะส่วน GUI) ควรลดความซับซ้อนลงเพื่อให้ผู้ที่มีประสบการณ์การใช้งานคอมพิวเตอร์เพียงเล็กน้อยเข้าใจและนำคำแนะนำไปใช้ได้ ในทางกลับกัน ข้อมูลก็ไม่ควรยาวเกินไปหรืออธิบายมากเกินไป (โดยเฉพาะส่วน CLI) จนทำให้ผู้เขียนโค้ดหมดความสนใจ
คุณสร้างสมดุลที่เหมาะสมได้โดยพูดถึงข้อกําหนดเบื้องต้นที่จุดเริ่มต้นของหน้า หรือเก็บส่วนที่ไม่บังคับไว้เพื่อให้ผู้ที่มีความเชี่ยวชาญข้ามไปได้
สำหรับการสร้างคำแปล กลุ่มเป้าหมายคือนักพัฒนาซอฟต์แวร์/ผู้ใช้ VLC ที่เข้าใจภาษาอังกฤษและภาษาที่จะแปลได้ดี
เครื่องมือ
เอกสารประกอบใหม่สร้างขึ้นโดย Sphinx และโฮสต์ใน ReadTheDocs รวมถึงมีการใช้ระบบควบคุมเวอร์ชันใน GitLab ก่อนหน้านี้ฉันเคยมีประสบการณ์ในการใช้ Git และ GitHub ซึ่งช่วยให้ฉันเข้าใจ GitLab ได้อย่างรวดเร็ว แม้ว่าจะมีฟีเจอร์บางอย่างที่ใช้เวลาเรียนรู้อยู่บ้าง
สำหรับ Sphinx นั้น เราได้อ่านเกี่ยวกับเครื่องมือนี้เมื่อเพื่อนที่ชื่นชอบโอเพนซอร์สคนนึงพูดถึงว่าองค์กรจำนวนมากใช้ Sphinx ในการสร้างเอกสารประกอบ (โดยมีตัวอย่างที่น่าสนใจอย่าง Blender ซึ่งใช้ Sphinx ในการสร้างคู่มือผู้ใช้[3] และเอกสารประกอบ API[4])
ฉันคุ้นเคยกับ ReadTheGoogle เอกสารเล็กน้อย ซึ่งเป็นเครื่องมือที่ดีสำหรับการกำหนดเวอร์ชันและการโฮสต์เอกสารทางเทคนิค เราจึงสร้างเอกสารประกอบของ VLC ได้โดยไม่มีปัญหามากนัก และเราคุ้นเคยกับ reStructured Text ซึ่งเป็นการจัดรูปแบบที่ใช้
สำหรับคำแปล VLC ใช้ Babel เพื่อสร้างไฟล์ .po เพื่อนำไปใช้งาน i18n และ l10n ปัจจุบันผมคุ้นเคยกับเวิร์กโฟลว์ของ Babel และวิธีสร้างไฟล์ .mo โดยใช้ Sphinx
ฉันตั้งใจจะใช้ระยะเวลาการผูกมัดเพื่อทำความคุ้นเคยกับรายละเอียดของเครื่องมือที่กล่าวถึงข้างต้น
รายการโฆษณาสดและไทม์ไลน์รายสัปดาห์
เราได้ครอบคลุมบางส่วนของการติดตั้ง อินเทอร์เฟซ เสียง วิดีโอ การเล่น ฯลฯ (ฟังก์ชันพื้นฐานส่วนใหญ่) ไว้แล้วในโปรเจ็กต์ปี 2019 ดังนั้นสำหรับโปรเจ็กต์ปี 2020 เราต้องการอัปเดตและแก้ไขส่วนการใช้งานขั้นสูงของเอกสารประกอบสำหรับผู้ใช้
ผลงานที่ 1 [สัปดาห์ที่ 1-2]: อัปเดตเอกสารประกอบเกี่ยวกับ Transcode ตามที่ระบุไว้ใน #7[5]
- การแปลง
- แปลงวิดีโอหลายรายการ
- เพิ่มโลโก้
- ผสานวิดีโอเข้าด้วยกัน
- แยกเสียงและแยกเสียงออกจากไฟล์
- ริป DVD
ผลงานที่ 2 [สัปดาห์ที่ 3-4]: อัปเดตการใช้ VLC เป็นปลั๊กอินเว็บ[6] ขณะทดสอบใน Firefox 77, Chrome 83 และ Edge 83
- การสร้างหน้าเว็บด้วยวิดีโอ
- แอตทริบิวต์แท็กที่ฝัง
- คำอธิบาย JavaScript API
ผลงานที่ 3 [สัปดาห์ที่ 5]: ทดสอบคำสั่งอินเทอร์เฟซบรรทัดคำสั่ง[7] และอัปเดตตามความเหมาะสม
- ยอดสตรีม
- การเลือกโมดูล
- ตัวเลือกเฉพาะรายการ
- ตัวกรอง
สัปดาห์ที่ 6: สัปดาห์สำรองสำหรับชิ้นงาน 3 รายการข้างต้น
ผลงานที่ 4 [สัปดาห์ที่ 7-8]: เตรียมพร้อมสำหรับการแปล นอกเหนือจากการอัปเดตแล้ว เราจะเตรียมการแปลเป็นภาษาอื่นๆ ซึ่งสำคัญเนื่องจากหลังจากการแปล ผู้ใช้ที่ไม่มีพื้นฐานภาษาอังกฤษจะสามารถอ่านเอกสารประกอบได้ (และอีกเรื่องหนึ่งคือ VLC จะก้าวไปอีกขั้นสู่การครองโลก[8])
ดังที่กล่าวไว้ในส่วนเครื่องมือของข้อเสนอนี้ ปัจจุบัน VLC ใช้ Babel ในการสร้างไฟล์ .po สำหรับการแปล ฉันจะบันทึกกระบวนการเพื่อให้ผู้ใช้/อาสาสมัครดำเนินการต่อไปนี้
- ดาวน์โหลดและสร้างเอกสารประกอบพื้นฐานในเครื่อง
- ใช้ Babel เพื่อสร้างไฟล์ที่จําเป็น
- ป้อนคำแปลสำหรับสตริง
- การสร้างเอกสารประกอบที่แปลแล้วโดยใช้ Sphinx
- ใช้การเปลี่ยนแปลง
ผลงานที่ 5 [สัปดาห์ที่ 9-10]: เตรียมเอกสารประกอบของข้อบังคับ ตามที่ได้หารือกับที่ปรึกษาแล้ว ฉันวางแผนที่จะเตรียมเอกสารของโมดูลโดยแบ่งเป็น 2 ส่วน
ส่วนที่ - I: การสร้างไฟล์ที่ใกล้กับโมดูลนั้นๆ ผ่านสคริปต์ที่หาตัวเลือกที่ถูกต้องจากฐานของโค้ด และดึงข้อมูลการใช้งานบรรทัดเดียว (และค่าเริ่มต้น) จากหน้า wiki ที่เกี่ยวข้อง ข้อมูลนี้จะเป็นฉบับร่างพื้นฐาน
ส่วนที่ 2: การสร้างโครงสร้างเฉพาะแพลตฟอร์มที่ลิงก์โมดูล+ปลั๊กอิน+ตัวเลือกทั้งหมดสำหรับแพลตฟอร์มหนึ่งๆ (Windows และ Fedora ด้วยหากมีเวลา)
การสร้างไฟล์ใกล้กับโมดูลจะช่วยให้มั่นใจได้ว่าเอกสารประกอบจะอยู่ใกล้กับซอร์สโค้ด เมื่อใช้แนวทางจากล่างขึ้นบน เอกสารประกอบของข้อบังคับหลักจะสร้างขึ้นจากการรวมไฟล์ที่สร้างในส่วนที่ 1 และใช้โครงสร้างที่สร้างในส่วนที่ 2 เป็นข้อมูลอ้างอิง
ไฟล์ที่สร้างผ่านการทำงานอัตโนมัติจะต้องได้รับการตรวจสอบ แต่สิ่งสำคัญอันดับแรกคือการสร้างเฟรมเวิร์กที่มีฟังก์ชันการทำงาน เมื่อดำเนินการเสร็จแล้วและขึ้นอยู่กับเวลาที่มี เราจะตรวจสอบไฟล์เพื่อยืนยันตัวเลือก เราให้ความสำคัญกับเฟรมเวิร์กนี้เนื่องจากเมื่อพร้อมใช้งาน นักพัฒนาซอฟต์แวร์และผู้ดูแลระบบจะเริ่มมีส่วนร่วมได้ด้วยการเพิ่ม Use Case ที่เกี่ยวข้อง
เนื้อหาพิเศษที่ส่ง [สัปดาห์ที่ 11]: เตรียมพร้อมสำหรับรุ่น 4.0 ในกรณีที่โครงการเป็นไปตามกำหนด ฉันขอเสนอการมอบโบนัส ตามที่กล่าวกับที่ปรึกษา การเตรียมพร้อมสำหรับรุ่น 4.0 หมายความว่าการมีเอกสารที่เสถียรและเกือบสมบูรณ์สำหรับเวอร์ชัน 3.0
เราจึงจะตรวจสอบเอกสารประกอบที่เสร็จสมบูรณ์แล้วของส่วนต่อไปนี้เพื่อยืนยันและอัปเดตวิธีการที่กล่าวถึง
- การใช้งานขั้นพื้นฐาน: สื่อ การเล่น เสียง วิดีโอ คำบรรยาย แป้นพิมพ์ลัด ไฟล์บันทึกเสียง การตั้งค่า เคล็ดลับและคำแนะนำ
- การใช้งานขั้นสูง: เพลเยอร์ อินเทอร์เฟซ การแปลงไฟล์ สตรีมมิง กรณีผิดปกติ
- ส่วนเสริม: ส่วนขยาย สกิน
สัปดาห์ที่ 12: สัปดาห์สำรองสำหรับชิ้นงาน 3 รายการข้างต้น + รายงานขั้นสุดท้าย
เหตุใดฉันจึงเหมาะกับโปรเจ็กต์นี้
ในฐานะผู้ที่ชื่นชอบเทคโนโลยี ฉันมีประสบการณ์ในการใช้/การทดสอบซอฟต์แวร์ และบางครั้งก็พยายามทำความเข้าใจฐานโค้ด อันที่จริงแล้ว การพยายามทำความเข้าใจฐานโค้ดขององค์กรโอเพนซอร์สเป็นครั้งแรกที่ทำให้ฉันตระหนักถึงความสำคัญของเอกสารประกอบอย่างแท้จริง นอกจากนี้ ในฐานะผู้ชื่นชอบเพลง ฉันมีประสบการณ์ในการปรับแต่ง VLC เป็นอย่างมาก :)
นอกจากนี้ ผมยังเป็นนักวิจัยและนักเขียนมาตลอดชีวิต ฉันจะเข้าใจสิ่งต่างๆ จริงๆ ก็ต่อเมื่อจดไว้ และนิสัยนี้ทำให้ฉันเป็นผู้จดบันทึกและจัดทำเอกสารที่มีประสิทธิภาพ
นิสัยทั้ง 2 อย่างนี้ทำให้ฉันเหมาะกับงานเขียนเอกสารทางเทคนิค ฉันสามารถค้นหาด้านเทคนิคต่างๆ พร้อมกับบันทึกผลการศึกษา/กระบวนการของฉันเพื่อให้ผู้ใช้เข้าใจได้
ลิงก์: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35