หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- VideoLAN
- ผู้เขียนด้านเทคนิค:
- เอดิออง แอนนี่ อาซิคโป
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารสำหรับผู้ใช้ VLC ให้ทันสมัย (เขียนใหม่)
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ขีดฆ่า
เอกสารสำหรับผู้ใช้ออกแบบมาเพื่อช่วยเหลือผู้ใช้ปลายทางในการใช้ผลิตภัณฑ์หรือบริการ เอกสารที่ดีสำหรับผู้ใช้นั้นมีความสำคัญมาก เนื่องจากช่วยให้ผู้ใช้ได้เรียนรู้วิธีใช้งานซอฟต์แวร์ รวมถึงฟีเจอร์ต่างๆ เคล็ดลับ คำแนะนำ และการแก้ปัญหาทั่วไปที่พบเมื่อใช้ซอฟต์แวร์ นอกจากนี้ ยังลดต้นทุนการสนับสนุนและเป็นส่วนหนึ่งของเอกลักษณ์องค์กรของผลิตภัณฑ์ กล่าวคือ ทีมนักพัฒนาแอปเอกสารที่ดีสำหรับผู้ใช้คือตัวบ่งชี้ถึงประสิทธิภาพของผลิตภัณฑ์
หากไม่มีเอกสารที่ดีสำหรับผู้ใช้ ผู้ใช้อาจไม่รู้วิธีทำสิ่งต่างๆ ข้างต้นได้อย่างมีประสิทธิภาพและประสิทธิผล เอกสารสำหรับผู้ใช้อาจมีบทบาทสำคัญในการรับประกันความสำเร็จของผลิตภัณฑ์ เนื่องจากการสื่อสารที่ดีจะเป็นหัวใจสำคัญของธุรกิจหรือผลิตภัณฑ์เสมอ และเอกสารที่ยอดเยี่ยมก็นำการสื่อสารนั้นมาใส่ไว้ในกรอบการทำงานที่จัดการได้ ซึ่งทุกคนจะเข้าถึงเพื่อความสำเร็จได้
ในขณะที่เขียนบทความนี้ มีการเข้าถึงเอกสารสำหรับผู้ใช้ VLC ถึง 4,634,065 ครั้ง และมีการดาวน์โหลดโปรแกรมเล่นสื่อ VLC ประมาณ 23 ล้านครั้งทุกเดือนจากเว็บไซต์หลัก แสดงให้เห็นว่ามีผู้คนจำนวนมากทั่วโลกใช้ VLC Media Player และอาจต้องการอ่านเอกสารของผู้ใช้เพื่อดูคำแนะนำเกี่ยวกับวิธีใช้โปรแกรมเล่นสื่อ อย่างไรก็ตาม เอกสารสำหรับผู้ใช้โปรแกรมเล่นสื่อ VLC ในปัจจุบันล้าสมัยและไม่สมบูรณ์ (แก้ไขครั้งล่าสุดเมื่อวันที่ 28 ของเดือนตุลาคม 2015) และชุมชน VideoLAN ต้องการใช้โครงการนี้เพื่อปรับปรุงเอกสารประกอบสำหรับผู้ใช้ เพื่อให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ราบรื่นเมื่อใช้โปรแกรมเล่นสื่อ VLC
สถานะปัจจุบัน
ในปัจจุบัน เอกสารสำหรับผู้ใช้มีอยู่บนหน้าเว็บวิกิ โปรแกรมดังกล่าวล้าสมัย ไม่สมบูรณ์ ไปยังส่วนต่างๆ หรือค้นหาข้อมูลได้ยาก ไม่ครอบคลุมข้อมูลเกี่ยวกับเวอร์ชันปัจจุบันของโปรแกรมเล่นสื่อ และสามารถแปลได้เฉพาะภาษาเยอรมันเท่านั้น ซึ่งทำให้เกิดความเสียหายอย่างมากสำหรับผู้ที่อ่านภาษาอังกฤษไม่ได้
เหตุใดเอกสารผู้ใช้ที่ฉันเสนอจึงถือเป็นการปรับปรุงที่มีอยู่แล้ว
เอกสารประกอบสำหรับผู้ใช้ที่เสนอจะจัดโครงสร้างเพื่อปรับปรุงและรับประกันประสิทธิภาพ ความสอดคล้อง และความสบายใจสำหรับผู้ใช้ปลายทาง โดยจะมีคำแนะนำเป็นลายลักษณ์อักษรและรูปภาพที่เกี่ยวข้อง รวมถึงคำแนะนำและคำอธิบายเกี่ยวกับวิธีใช้แต่ละฟีเจอร์ของโปรแกรมเล่นสื่อ VLC ข้อมูลล่าสุด ไปยังส่วนต่างๆ ได้ง่าย เข้าใจได้ และแปลได้ในภาษาหลักๆ อย่างน้อย 5 ภาษา
ที่ปรึกษา: Jean-Baptiste, Alex, Simon
การวิเคราะห์
Jean-Baptiste และฉันพูดคุยกันเกี่ยวกับสภาพแวดล้อมใหม่ที่จะย้ายข้อมูลเอกสารของผู้ใช้ปัจจุบันไปปรับปรุง และเขาได้แชร์ลิงก์ 2 ลิงก์ที่แสดงที่เก็บ Gitlab ของไฟล์ต้นฉบับที่เขียนด้วย Sphinx และเอกสารหลักที่โฮสต์ใน "อ่านเอกสาร" ซึ่งเขาบอกว่าพวกเขาคาดหวังว่าเอกสารใหม่จะคล้ายกับเอกสารนี้ ฉันได้ค้นคว้าข้อมูลมากมายเกี่ยวกับเครื่องมือเหล่านี้เพื่อให้เข้าใจวิธีการทำงานได้ดียิ่งขึ้น
สฟิงซ์
Sphinx เป็นโซลูชันที่แข็งแกร่งและสมบูรณ์สำหรับการจัดทำเอกสารซอฟต์แวร์ ซึ่งประกอบด้วยฟีเจอร์ต่างๆ มากมายที่ผู้เขียนคาดหวัง เช่น การเผยแพร่จากแหล่งเดียว การใช้เนื้อหาซ้ำ รวมถึงแบบมีเงื่อนไข ประกอบด้วยเนื้อหาตามประเภทและแท็ก ธีม HTML สำหรับผู้ใหญ่หลายแบบที่มอบประสบการณ์ของผู้ใช้ที่ยอดเยี่ยมทั้งในอุปกรณ์เคลื่อนที่และเดสก์ท็อป การอ้างอิงระหว่างหน้า เอกสาร และโปรเจ็กต์ต่างๆ การรองรับดัชนีและอภิธานศัพท์ รวมถึงการรองรับการปรับให้เป็นสากล นอกจากนี้ยังใช้ reStructuredText เป็นภาษามาร์กอัป จุดแข็งหลายอย่างก็มาจากพลังและความตรงไปตรงมาของ reStructuredText รวมถึงความสามารถในการแปลเอกสาร
อ่านเอกสาร
อ่านเอกสารจะช่วยลดความซับซ้อนของเอกสารประกอบซอฟต์แวร์ด้วยการสร้าง กำหนดเวอร์ชัน และโฮสต์เอกสารโดยอัตโนมัติ ข้อมูลไม่เคยซิงค์กัน กล่าวคือ เมื่อใดก็ตามที่คุณพุชโค้ดไปยังระบบควบคุมเวอร์ชันที่คุณชื่นชอบ ไม่ว่าจะเป็น Git, Mercurial, Bazaar หรือ Subversion โปรแกรมอ่านเอกสารจะสร้างเอกสารให้โดยอัตโนมัติเพื่อให้โค้ดและเอกสารประกอบเป็นปัจจุบันอยู่เสมอ เพราะมีหลายเวอร์ชัน Read เอกสารสามารถโฮสต์และสร้างเอกสารหลายเวอร์ชันได้ ดังนั้นการมีเอกสารเวอร์ชัน 1.0 และเอกสารเวอร์ชัน 2.0 ของคุณจึงง่ายพอๆ กับการมีสาขาหรือแท็กแยกต่างหากในระบบควบคุมเวอร์ชัน อ่านเอกสารได้ฟรี เป็นโอเพนซอร์สและมีเอกสารประกอบสำหรับโครงการโอเพนซอร์สทั้งขนาดเล็กและใหญ่เกือบ 100,000 โครงการในภาษามนุษย์และคอมพิวเตอร์เกือบทุกภาษา
จุดศูนย์กลาง
Sphinx เป็นเครื่องมือที่ทรงประสิทธิภาพอย่างน่าทึ่ง "อ่านเอกสารเลย" ซึ่งสร้างขึ้นด้านบนเพื่อให้บริการโฮสติ้งสำหรับเอกสารของ Sphinx ที่ช่วยอัปเดตเอกสารของคุณให้ทันสมัยในทุกเวอร์ชัน เมื่อใช้งานร่วมกัน เครื่องมือเหล่านี้คือชุดเครื่องมือที่ยอดเยี่ยมที่นักพัฒนาซอฟต์แวร์และนักเขียนด้านเทคนิคสามารถใช้เพื่อสร้างเอกสารประกอบสำหรับผู้ใช้ที่ดีที่สุดสำหรับผู้ใช้ปลายทาง
Sphinx รองรับการแปลเอกสารประกอบเป็นภาษาต่างๆ โดยจะรองรับการควบคุมเวอร์ชันที่จะใช้ในการจัดการเอกสารประกอบ ต่างจาก wiki ปัจจุบันที่ทุกคนสามารถแก้ไขและไม่เพิ่มข้อมูลที่ถูกต้องตรงที่ ระบบควบคุมเวอร์ชันนี้ช่วยให้แน่ใจว่าการเปลี่ยนแปลงทั้งหมดจะได้รับการตรวจสอบก่อนทำการรวมเข้ากับที่เก็บหลัก การควบคุมเวอร์ชันจะทำให้เอกสารช่วยเพิ่มการมีส่วนร่วมแบบโอเพนซอร์สในโครงการได้เพราะผู้คนอาจสร้างปัญหา เปิดคำขอดึงข้อมูล ฯลฯ สฟิงซ์และอ่านเอกสารจะใช้โดยรายการชุมชนและชุมชนอื่นๆ ที่ยอดเยี่ยม เช่น ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs เป็นต้น และเป็นเครื่องมือที่ยอดเยี่ยมสำหรับใช้จัดทำเอกสารใหม่สำหรับผู้ใช้ VLC
ฉันไม่ได้อ่านข้อมูลเกี่ยวกับเครื่องมือเหล่านี้เท่านั้น แต่ยังสร้างตัวอย่างพื้นฐานขึ้นมาด้วย จากลิงก์ https://gitlab.com/Didicodes/demo-vlc-user-documentation ไปยังที่เก็บ Gitlab ของฉัน คุณจะดูเวอร์ชันที่โฮสต์ใน 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 และ ReadtheDocs
- นำรูปภาพและข้อมูลที่ล้าสมัยออก
- โปรดเขียนเอกสารประกอบให้ผู้ใช้ใหม่เพื่อให้เข้าใจง่ายขึ้น
- ตั้งค่าสำหรับการแปลโดยใช้การทำให้เป็นสากล Sphinx
- ทำให้ชุมชนเอกสารขับเคลื่อนด้วย เพื่อให้ผู้ใช้รายงานหรือแก้ไขปัญหาที่พบขณะอ่านเอกสารได้
ทำไมต้องเป็นโครงการนี้
ฉันเชื่อมาตลอดว่าการเขียนโค้ด การแก้ปัญหา และการสร้างซอฟต์แวร์จะเต็มศักยภาพเมื่อคุณสามารถให้ความรู้แก่ผู้อื่นผ่านการเขียนได้ด้วย โดยส่วนตัวแล้ว ผมสนใจความพยายามของชุมชน VideoLAN ในการสร้างโซลูชันซอฟต์แวร์ฟรีสำหรับมัลติมีเดียมาโดยตลอด เมื่อตอนเด็กๆ ผมใช้โปรแกรมเล่นสื่อ VLC เป็นซอฟต์แวร์ที่ผมใช้เวลาฟังเพลงหรือดูภาพยนตร์มาโดยตลอด เพราะเสียงดังมากและมีฟีเจอร์ต่างๆ มากมาย ฉันรู้สึกเป็นเกียรติที่ได้ร่วมงานกับชุมชนที่มีส่วนร่วมในการสร้างความยอดเยี่ยมในวัยเด็กของฉัน
เหตุใดฉันจึงเป็นบุคคลที่ถูกต้องสำหรับโปรเจ็กต์นี้
ฉันเชื่อว่าฉันเป็นบุคคลที่ถูกต้องในโครงการนี้ เนื่องจาก
- ฉันมีประสบการณ์ที่ผ่านมาในการปรับปรุงเอกสารขององค์กรและสามารถใช้ระบบควบคุมเวอร์ชันใดก็ได้ ดังนั้นการใช้คำสั่งใน Gitab จึงไม่เป็นปัญหา นอกจากนี้ สิ่งที่เป็นแรงผลักดันให้ผมทำโปรเจ็กต์ที่สร้างคุณค่าให้กับผู้คน
- ผมเชื่อว่าหากต้องการให้ใครสักคนทำอะไร อย่างมีประสิทธิภาพมากที่สุด คุณก็ควรบันทึกเอาไว้ การจัดทำเอกสารขั้นตอนต่างๆ ของคุณจะช่วยรับประกันประสิทธิภาพ ความสอดคล้อง และความสบายใจสำหรับทุกคนที่เกี่ยวข้อง
- ฉันทราบความต้องการของผู้ใช้ VLC เพราะฉันเป็นหนึ่งในนั้น วิธีนี้จะช่วยให้สามารถเขียนเอกสารในแบบที่ผู้ใช้คนอื่นๆ ทั่วโลกเข้าใจได้อย่างรวดเร็ว