โปรเจ็กต์ VLC

หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ 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