หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- VLC
- ผู้เขียนด้านเทคนิค:
- อภิเษก ประตั๊บสิงห์
- ชื่อโปรเจ็กต์:
- ดำเนินการปรับเอกสารผู้ใช้ VLC ให้ทันสมัยต่อ
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
สถานะปัจจุบันของเอกสารประกอบ
เอกสารสำหรับผู้ใช้ VLC อยู่ระหว่างการปรับให้ทันสมัยและอัปเดต การเปลี่ยนแปลงนี้อยู่ระหว่างดำเนินการจากเอกสารฉบับเก่าที่ใช้วิกิพีเดีย [1] ไปเป็นเอกสารประกอบของสฟิงซ์ที่สร้างขึ้นสำหรับผู้ใช้ที่ทันสมัย[2] ซึ่งโฮสต์อยู่ใน ReadTheDocs
กลุ่มเป้าหมาย
กลุ่มเป้าหมายจะเป็นทั้งผู้ใช้ที่อยากรู้อยากเห็นและต้องการใช้ฟีเจอร์ต่างๆ ของโปรแกรมเล่นสื่อ VLC นอกเหนือไปจากโปรแกรมเล่นสื่อทั่วไป ทั้งยังช่วยนักพัฒนาซอฟต์แวร์ด้วยเพราะเป็นคู่มืออ้างอิงที่ใช้งานง่าย เราจึงวางแผนที่จะใส่ทั้งวิธีการแบบ GUI (รวมถึงรูปภาพที่เกี่ยวข้อง) และวิธีการแบบ CLI (รวมถึงข้อมูลโค้ด) เพื่อให้ผู้ใช้มีอิสระในการเลือก
ฉันเชื่อว่าภาษาของเอกสารประกอบ (โดยเฉพาะส่วน GUI) ควรสั้นลงมากพอที่ผู้ที่ไม่ได้ใช้คอมพิวเตอร์ซึ่งทำงานอยู่เพียงเล็กน้อยจะสามารถเข้าใจและใช้งานคู่มือนี้ได้ ในทางกลับกัน แท็กไม่ควรยาวหรืออธิบายง่ายเกินไป (โดยเฉพาะส่วน CLI) ที่นักเขียนโค้ดจะหมดความสนใจ
คุณจะหาจุดสมดุลที่เหมาะสมได้โดยพูดถึงสิ่งที่ต้องมีก่อนตอนเริ่มต้นของหน้าเว็บ หรือเก็บส่วนที่ไม่บังคับซึ่งผู้เชี่ยวชาญสามารถข้ามได้
สำหรับการสร้างการแปล กลุ่มเป้าหมายคือนักพัฒนาซอฟต์แวร์/ผู้ใช้ VLC ที่เข้าใจภาษาอังกฤษและภาษาที่จะแปลเป็นอย่างดี
เครื่องมือ
Sphinx จะสร้างเอกสารประกอบใหม่นี้และโฮสต์ไว้บน ReadTheDocs และระบบควบคุมเวอร์ชันใช้งานใน GitLab ฉันเคยมีประสบการณ์ในการใช้ Git และ GitHub มาก่อน ซึ่งช่วยให้ฉันเริ่มคุ้นเคยกับ GitLab ได้ แม้จะมีบางฟีเจอร์ที่ต้องใช้เวลาเรียนรู้
สําหรับ Sphinx ผมได้อ่านเกี่ยวกับเรื่องนี้เมื่อเพื่อนๆ ผู้ชื่นชอบโอเพนซอร์สแสดงความคิดเห็นถึงจํานวนองค์กรที่ใช้ระบบนี้ในการสร้างเอกสารประกอบ (โดยตัวอย่างที่โดดเด่นของ Blender ซึ่งใช้ Sphinx ในการสร้างคู่มือผู้ใช้ [3] และเอกสาร API[4])
ฉันคุ้นเคยกับ ReadTheDocuments ซึ่งเป็นเครื่องมือที่ดีสำหรับการกำหนดเวอร์ชันและสำหรับการโฮสต์เอกสารด้านเทคนิค ดังนั้นฉันจึงสามารถสร้างเอกสารประกอบ VLC ขึ้นมาได้โดยไม่มีปัญหาอะไรมาก และคุ้นเคยกับข้อความที่มีโครงสร้างใหม่ ซึ่งเป็นรูปแบบที่ใช้
สำหรับการแปล VLC ใช้ Babel ในการสร้างไฟล์ .po เพื่อใช้งาน i18n และ l10n ตอนนี้ฉันคุ้นเคยกับเวิร์กโฟลว์ของ Babel และวิธีการสร้างไฟล์ .mo โดยใช้ Sphinx แล้ว
ฉันตั้งใจจะใช้ระยะเวลาสร้างความสนิทสนมเพื่อทำความคุ้นเคยกับความซับซ้อนของเครื่องมือที่กล่าวถึงข้างต้น
การแสดงโฆษณาและไทม์ไลน์รายสัปดาห์
โปรเจ็กต์ปี 2019 นี้ครอบคลุมส่วนต่างๆ ของการติดตั้ง อินเทอร์เฟซ เสียง วิดีโอ การเล่น ฯลฯ (ฟังก์ชันพื้นฐานส่วนใหญ่) อยู่แล้ว ดังนั้น สำหรับโครงการปี 2020 เราจึงต้องการอัปเดตข้อมูลในส่วนการใช้งานขั้นสูงในเอกสารสำหรับผู้ใช้
นำส่งได้ 1 [สัปดาห์ที่ 1-2]: อัปเดตเอกสารประกอบของการแปลง ตามที่ระบุไว้ใน #7[5]
- การแปลง
- แปลงวิดีโอหลายรายการ
- เพิ่มโลโก้
- รวมวิดีโอเข้าด้วยกัน
- ดึงเสียงและแยกเสียงออกจากไฟล์
- ดึงดีวีดี
แสดงผลได้ 2 [สัปดาห์ที่ 3-4]: อัปเดตโดยใช้ VLC เป็นปลั๊กอินบนเว็บ[6] ขณะทดสอบใน Firefox 77, Chrome 83 และ Edge 83
- การสร้างหน้าเว็บที่มีวิดีโอ
- แอตทริบิวต์แท็กฝัง
- คำอธิบาย JavaScript API
แสดงผล 3 [สัปดาห์ที่ 5]: ทดสอบคำสั่งอินเทอร์เฟซบรรทัดคำสั่ง[7] และอัปเดตให้เหมาะสม
- ยอดสตรีม
- การเลือกโมดูล
- ตัวเลือกเฉพาะรายการ
- ฟิลเตอร์
สัปดาห์ที่ 6: สัปดาห์บัฟเฟอร์สำหรับสิ่งที่ส่งมอบ 3 อย่างข้างต้น
แสดงผล 4 [สัปดาห์ที่ 7-8]: เตรียมพร้อมสำหรับการแปล นอกจากการอัปเดตแล้ว ฉันจะเตรียมการแปลเป็นภาษาอื่นๆ ด้วย ซึ่งสำคัญเช่นหลังการแปล ผู้ใช้ที่ไม่มีภูมิหลังเป็นภาษาอังกฤษจะสามารถอ่านเอกสารประกอบได้ (และหมายเหตุอีกอย่างคือ VLC จะเข้าใกล้การบรรลุ World Domination[8] ไปอีกก้าว)
ดังที่กล่าวไว้ในส่วนเครื่องมือของข้อเสนอ ปัจจุบัน VLC ใช้ Babel ในการสร้างไฟล์ .po สำหรับการแปล ฉันจะบันทึกกระบวนการสำหรับผู้ใช้/อาสาสมัครเพื่อ:
- ดาวน์โหลดและสร้างเอกสารประกอบพื้นฐานภายในเครื่อง
- ใช้ Babel เพื่อสร้างไฟล์ที่ต้องการ
- ป้อนคำแปลสำหรับสตริง
- กำลังสร้างเอกสารประกอบที่แปลแล้วโดยใช้ Sphinx
- ยืนยันการเปลี่ยนแปลง
แสดงผล 5 [สัปดาห์ที่ 9-10]: เตรียมเอกสารประกอบสำหรับโมดูลต่างๆ ตามที่ได้พูดคุยกับที่ปรึกษา ฉันวางแผนที่จะเตรียมเอกสารประกอบสำหรับโมดูลโดยแบ่งออกเป็น 2 ส่วน
ส่วนที่ 1: การสร้างไฟล์ใกล้กับโมดูลโดยใช้สคริปต์ที่มองหาตัวเลือกที่ถูกต้องจากฐานของโค้ด และดึงข้อมูลการใช้งานบรรทัดเดียว (และค่าเริ่มต้น) จากหน้า Wiki ที่เกี่ยวข้องกัน ส่วนนี้จะเป็นฉบับร่างพื้นฐาน
ส่วนที่ 2: การสร้างโครงสร้างเฉพาะแพลตฟอร์มซึ่งเชื่อมโยงโมดูล+ปลั๊กอิน+ตัวเลือกทั้งหมดสำหรับแพลตฟอร์มหนึ่งๆ (Windows และสำหรับ Fedora หากมีเวลาเพียงพอ)
การสร้างไฟล์ใกล้กับโมดูลจะช่วยให้เอกสารอยู่ใกล้กับซอร์สโค้ด เอกสารโมดูลหลักจะสร้างขึ้นจากการรวมไฟล์ต่างๆ ที่สร้างขึ้นในส่วนที่ 1 และใช้โครงสร้างที่สร้างขึ้นในส่วนที่ 2 เป็นข้อมูลอ้างอิง ด้วยวิธีการจากด้านล่าง
ไฟล์ที่สร้างขึ้นผ่านการทำงานอัตโนมัติจะต้องได้รับการตรวจสอบ แต่สิ่งสำคัญอันดับแรกคือการสร้างเฟรมเวิร์กที่ใช้งานได้ เมื่อได้รับข้อมูลดังกล่าวแล้ว เราจะตรวจสอบไฟล์เพื่อยืนยันตัวเลือกต่างๆ ตามเวลาที่มีอยู่ เฟรมเวิร์กจะได้รับการจัดลำดับความสำคัญทันทีที่พร้อมใช้งาน นักพัฒนาซอฟต์แวร์และผู้บำรุงรักษาสามารถเริ่มมีส่วนร่วมได้โดยเพิ่มกรณีการใช้งานที่เกี่ยวข้อง
โบนัสที่สามารถส่งมอบได้ [สัปดาห์ที่ 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.blelannder.org/api/current/index.html [5] https://docs.blender.org/manual/en/latest/ [4] https://docs.blelannder.org/api/current/index.html [5]