มีส่วนร่วมใน MDN Web Docs

MDN Web Docs จัดทำเอกสารเกี่ยวกับแพลตฟอร์มเว็บมานานกว่าสิบสองปีแล้ว และขณะนี้เป็นความพยายามข้ามแพลตฟอร์มด้วยการสนับสนุนและคณะกรรมการที่ปรึกษาที่มีสมาชิกจาก Google, Microsoft และ Samsung รวมถึงผู้ที่เป็นตัวแทนของ Firefox สิ่งที่เป็นพื้นฐานของ MDN คือความพยายามของชุมชนอย่างมาก โดยชุมชนเว็บช่วยสร้างและดูแลรักษาเอกสาร ในบทความนี้ ฉันจะให้คำแนะนำเกี่ยวกับสถานที่ที่คุณสามารถช่วยสนับสนุน MDN ได้และต้องทำอย่างไร

หากคุณไม่เคยมีส่วนร่วมในโครงการโอเพ่นซอร์สมาก่อน MDN เป็นจุดเริ่มต้นที่ยอดเยี่ยม ทักษะที่จำเป็นมีตั้งแต่การแก้ไขการคัดลอก การแปลจากภาษาอังกฤษเป็นภาษาอื่น ทักษะ HTML และ CSS สำหรับการสร้างตัวอย่างเชิงโต้ตอบ หรือความสนใจในความเข้ากันได้ของเบราว์เซอร์สำหรับการอัปเดตข้อมูลความเข้ากันได้ของเบราว์เซอร์ สิ่งที่คุณไม่ต้องทำคือเขียนโค้ดจำนวนมากเพื่อบริจาค มันตรงไปตรงมามาก และเป็นวิธีที่ยอดเยี่ยมในการตอบแทนชุมชน หากคุณเคยพบว่าเอกสารเหล่านี้มีประโยชน์

การมีส่วนร่วมในหน้าเอกสาร

ที่แรกที่คุณอาจต้องการมีส่วนร่วมคือเอกสาร MDN เอง MDN เป็นวิกิ ดังนั้น คุณสามารถเข้าสู่ระบบและเริ่มช่วยเหลือโดยแก้ไขหรือเพิ่มเอกสารประกอบสำหรับ CSS, HTML, JavaScript หรือส่วนอื่นๆ ของแพลตฟอร์มเว็บที่ครอบคลุมโดย MDN

หากต้องการเริ่มแก้ไข คุณต้องเข้าสู่ระบบโดยใช้ GitHub ตามปกติในวิกิ จะมีรายการผู้แก้ไขหน้าใด ๆ อยู่ในรายการ และส่วนนี้จะใช้ชื่อผู้ใช้ GitHub ของคุณ หากคุณดูหน้าใด ๆ ของผู้ให้ข้อมูลร่วมกันของ MDN อยู่ที่ด้านล่างของหน้า รูปภาพด้านล่างจะแสดงผู้ร่วมให้ข้อมูลปัจจุบันไปยังหน้านั้นบน CSS Grid Layout

แก้ไขอะไรได้บ้าง

สิ่งที่คุณอาจพิจารณาในฐานะบรรณาธิการกำลังแก้ไขข้อผิดพลาดทางไวยากรณ์และการพิมพ์ผิดที่ชัดเจน หากคุณเป็นนักพิสูจน์อักษรและบรรณาธิการที่ดี คุณอาจสามารถปรับปรุงความสามารถในการอ่านเอกสารได้ด้วยการแก้ไขข้อผิดพลาดการสะกดคำหรือข้อผิดพลาดอื่นๆ

นอกจากนี้ คุณอาจพบข้อผิดพลาดทางเทคนิค หรือที่ใดที่หนึ่งที่ข้อมูลจำเพาะมีการเปลี่ยนแปลง และตำแหน่งที่การอัปเดตหรือการชี้แจงจะเป็นประโยชน์ ด้วยคุณสมบัติของแพลตฟอร์มเว็บที่ครอบคลุมโดย MDN และอัตราการเปลี่ยนแปลง มันง่ายมากสำหรับสิ่งต่าง ๆ ที่จะล้าสมัย หากคุณพบเห็นบางสิ่ง - แก้ไขมัน!

คุณอาจใช้ความรู้เฉพาะบางอย่างที่คุณต้องเพิ่มข้อมูลเพิ่มเติม ตัวอย่างเช่น Eric Bailey ได้เพิ่มส่วนข้อกังวลด้านการเข้าถึงข้อมูลลงในหลายหน้า นี่เป็นความพยายามที่ยอดเยี่ยมในการเน้นย้ำถึงสิ่งที่เราควรคำนึงถึงเมื่อใช้บางสิ่ง

ที่อื่นที่คุณสามารถเพิ่มในหน้าได้คือการเพิ่มลิงก์ "ดูเพิ่มเติม" สิ่งเหล่านี้อาจเป็นลิงก์ไปยังส่วนอื่นๆ ของ MDN หรือไปยังแหล่งข้อมูลภายนอก เมื่อเพิ่มทรัพยากรภายนอก สิ่งเหล่านี้ควรมีความเกี่ยวข้องอย่างมากกับคุณสมบัติ องค์ประกอบ หรือเทคนิคที่อธิบายในเอกสารนั้น ผู้สมัครที่ดีน่าจะเป็นบทช่วยสอนที่สาธิตวิธีใช้ฟีเจอร์นั้น ซึ่งจะทำให้ผู้อ่านค้นหาข้อมูลเป็นขั้นตอนต่อไปที่มีคุณค่า

จะแก้ไขเอกสารได้อย่างไร?

เมื่อคุณเข้าสู่ระบบแล้ว คุณจะเห็นลิงก์ไปยังแก้ไขบนหน้าต่างๆ ใน ​​MDN การคลิกที่นี่จะนำคุณไปสู่ตัวแก้ไขแบบ WYSIWYG สำหรับแก้ไขเนื้อหา การแก้ไขช่วงแรกๆ ของคุณมักจะเป็นการเปลี่ยนแปลงเล็กๆ น้อยๆ ซึ่งในกรณีนี้ คุณควรจะสามารถติดตามและแก้ไขข้อความได้ หากคุณกำลังทำการแก้ไขอย่างละเอียด คุณควรดูคู่มือสไตล์ก่อน นอกจากนี้ยังมีคำแนะนำในการใช้ WYSIWYG Editor

หลังจากแก้ไขแล้ว คุณสามารถแสดงตัวอย่างแล้วเผยแพร่ได้ ก่อนเผยแพร่ เป็นความคิดที่ดีที่จะอธิบายสิ่งที่คุณเพิ่มเข้าไป และเหตุใดจึงใช้ช่องความคิดเห็นเกี่ยวกับการแก้ไข

การแปลภาษา

พวกเราที่ใช้ภาษาอังกฤษเป็นภาษาแรกนั้นโชคดีอย่างเหลือเชื่อเมื่อพูดถึงข้อมูลบนเว็บ สามารถรับข้อมูลเกือบทั้งหมดที่เราอยากได้ในภาษาของเราเอง หากคุณสามารถแปลหน้าภาษาอังกฤษเป็นภาษาอื่นๆ ได้ คุณสามารถช่วยแปล MDN Web Docs ได้ ทำให้ข้อมูลทั้งหมดนี้พร้อมใช้งานสำหรับผู้คนจำนวนมากขึ้น

หากคุณคลิกที่ไอคอนภาษาบนหน้าใดๆ คุณจะเห็นว่าข้อมูลนั้นได้รับการแปลเป็นภาษาใดบ้าง และคุณสามารถเพิ่มการแปลของคุณเองตามข้อมูลบนหน้า การแปลหน้า MDN

ตัวอย่างเชิงโต้ตอบ

ตัวอย่างเชิงโต้ตอบบน MDN คือตัวอย่างที่คุณจะเห็นที่ด้านบนสุดของหลายๆ หน้าของ MDN เช่น หน้านี้สำหรับคุณสมบัติ grid-area

ตัวอย่างเหล่านี้อนุญาตให้ผู้เยี่ยมชม MDN ลองใช้ค่าต่างๆ สำหรับคุณสมบัติ CSS หรือลองใช้ฟังก์ชัน JavaScript ตรงนั้นบน MDN โดยไม่จำเป็นต้องมุ่งหน้าไปยังสภาพแวดล้อมการพัฒนาเพื่อทำเช่นนั้น โครงการที่จะเพิ่มตัวอย่างเหล่านี้กำลังดำเนินการอยู่ประมาณหนึ่งปี คุณสามารถอ่านเกี่ยวกับโครงการและความคืบหน้าจนถึงปัจจุบันได้ในโพสต์ การนำตัวอย่างเชิงโต้ตอบมาสู่ MDN

เนื้อหาสำหรับตัวอย่างเชิงโต้ตอบเหล่านี้อยู่ในที่เก็บ GitHub ตัวอย่างเชิงโต้ตอบ ตัวอย่างเช่น หากคุณต้องการค้นหาตัวอย่างสำหรับพื้นที่กริด คุณจะพบมันใน repo นั้นภายใต้ live-examples/css-examples/grid ใต้โฟลเดอร์นั้น คุณจะพบไฟล์สองไฟล์สำหรับ grid-area ไฟล์ HTML และ CSS

grid-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

ตัวอย่างเชิงโต้ตอบเป็นเพียงตัวอย่างเล็กๆ ซึ่งใช้คลาสและรหัสมาตรฐานบางอย่างเพื่อให้กรอบงานสามารถรับตัวอย่างและทำให้เป็นแบบโต้ตอบได้ โดยผู้เยี่ยมชมหน้าเว็บที่ต้องการดูอย่างรวดเร็วสามารถเปลี่ยนค่าได้ ทำงาน ในการเพิ่มหรือแก้ไข Interactive Example ก่อนอื่นให้แยก repo ตัวอย่างเชิงโต้ตอบ โคลนไปยังเครื่องของคุณและทำตามคำแนะนำในหน้า Contributing เพื่อติดตั้งแพ็คเกจที่จำเป็นจาก npm และสามารถสร้างและทดสอบตัวอย่างในเครื่องได้

จากนั้นสร้างสาขาและแก้ไขหรือสร้างตัวอย่างใหม่ของคุณ เมื่อคุณพอใจแล้ว ให้ส่งคำขอดึงไปที่ repo ตัวอย่างเชิงโต้ตอบเพื่อขอให้ตรวจสอบตัวอย่างของคุณ ในการทำให้ตัวอย่างมีความสอดคล้องกัน บทวิจารณ์นั้นค่อนข้างจะจู้จี้จุกจิก แต่ควรชี้ให้เห็นถึงการเปลี่ยนแปลงที่คุณต้องทำอย่างชัดเจน เพื่อให้คุณสามารถอัปเดตตัวอย่างของคุณและให้มีการอนุมัติ รวม และเพิ่มไปยังเพจ MDN

ด้วย CSS เกือบทั้งหมดที่ครอบคลุมในขณะนี้ (นอกเหนือจากตัวอย่าง JavaScript) MDN กำลังมองหาความช่วยเหลือในการสร้างตัวอย่าง HTML มีคำแนะนำเกี่ยวกับวิธีการเริ่มต้นใช้งานในโพสต์บนฟอรัมวาทกรรม MDN ตรวจดูโพสต์นั้นเนื่องจากมีลิงก์ไปยังเอกสารของ Google ที่คุณสามารถใช้เพื่อระบุว่าคุณกำลังดำเนินการกับตัวอย่างเฉพาะ รวมถึงข้อมูลที่เป็นประโยชน์อื่นๆ

ตัวอย่างเชิงโต้ตอบมีประโยชน์อย่างเหลือเชื่อสำหรับผู้ที่สำรวจแพลตฟอร์มเว็บ ดังนั้นการเพิ่มในโครงการจึงเป็นวิธีที่ยอดเยี่ยมในการมีส่วนร่วม การมีส่วนร่วมกับตัวอย่าง CSS หรือ HTML ต้องใช้ความรู้เกี่ยวกับ CSS และ HTML บวกกับความสามารถในการคิดการสาธิตที่ชัดเจน จุดสุดท้ายนี้มักจะเป็นส่วนที่ยากที่สุด ฉันได้สร้าง CSS Interactive Examples จำนวนมาก และใช้เวลาคิดตัวอย่างที่ดีที่สุดสำหรับแต่ละคุณสมบัติมากกว่าที่ฉันเขียนโค้ดจริงๆ

ข้อมูลความเข้ากันได้ของเบราว์เซอร์

เมื่อไม่นานมานี้ ข้อมูลความเข้ากันได้ของเบราว์เซอร์ที่แสดงบนหน้า MDN ได้เริ่มได้รับการอัปเดตผ่านโครงการความเข้ากันได้ของเบราว์เซอร์ โปรเจ็กต์นี้กำลังพัฒนาข้อมูลที่เข้ากันได้กับเบราว์เซอร์ในรูปแบบ JSON ซึ่งสามารถแสดงตารางความเข้ากันได้บน MDN แต่ยังเป็นข้อมูลที่เป็นประโยชน์สำหรับวัตถุประสงค์อื่นด้วย

ข้อมูลความเข้ากันได้ของเบราว์เซอร์อยู่บน GitHub และหากคุณพบหน้าที่มีข้อมูลที่ไม่ถูกต้องหรือยังคงใช้ตารางเก่าอยู่ คุณสามารถส่งคำขอดึงได้ ที่เก็บมีข้อมูลการสนับสนุน อย่างไรก็ตาม วิธีที่ง่ายที่สุดในการเริ่มต้นคือการแก้ไขตัวอย่างที่มีอยู่ ฉันเพิ่งอัปเดตข้อมูลสำหรับคุณสมบัติ CSS shape-outside พร็อพเพอร์ตี้มีข้อมูลบางส่วนในรูปแบบใหม่แล้ว แต่ยังไม่สมบูรณ์และไม่ถูกต้อง

ในการแก้ไขข้อมูลนี้ ก่อนอื่น ฉันได้แยกข้อมูลความเข้ากันได้ของเบราว์เซอร์ ฉันมีส้อมของตัวเอง จากนั้นฉันก็ลอกแบบไปที่เครื่องของฉันและสร้างสาขาใหม่เพื่อทำการเปลี่ยนแปลงของฉัน

เมื่อฉันมีสาขาใหม่แล้ว ฉันพบไฟล์ JSON สำหรับ shape-outside และสามารถแก้ไขได้ ฉันมีความคิดที่ดีเกี่ยวกับการสนับสนุนเบราว์เซอร์สำหรับพร็อพเพอร์ตี้ ฉันยังใช้ตัวอย่างสดในหน้า MDN รูปร่างภายนอกเพื่อทดสอบเพื่อดูการสนับสนุนเมื่อไม่แน่ใจ ดังนั้นการแก้ไขจึงเป็นกรณีของการทำงานผ่านไฟล์ การตรวจสอบหมายเลขเวอร์ชันที่แสดงไว้เพื่อรองรับคุณสมบัติและอัปเดตรายการที่ไม่ถูกต้อง

เนื่องจากไฟล์อยู่ในรูปแบบ JSON จึงค่อนข้างตรงไปตรงมาในการแก้ไขในโปรแกรมแก้ไขข้อความใดๆ ไฟล์ .editorconfig อธิบายกฎการจัดรูปแบบอย่างง่ายสำหรับเอกสารเหล่านี้ นอกจากนี้ยังมีเคล็ดลับที่เป็นประโยชน์ในรายการตรวจสอบนี้อีกด้วย

เมื่อคุณทำการแก้ไขแล้ว คุณสามารถคอมมิตการเปลี่ยนแปลงของคุณ พุชสาขาของคุณไปที่ส้อมของคุณ แล้วสร้างคำขอดึงไปยังที่เก็บข้อมูลความเข้ากันได้ของเบราว์เซอร์ มีแนวโน้มว่า เช่นเดียวกับตัวอย่างสด ผู้ตรวจทานจะมีการเปลี่ยนแปลงบางอย่างให้คุณทำ ใน PR ของฉันสำหรับข้อมูล Shapes ฉันมีข้อผิดพลาดเล็กน้อยเกี่ยวกับวิธีการตั้งค่าสถานะข้อมูลและจำเป็นต้องทำการเปลี่ยนแปลงบางอย่างกับลิงก์ สิ่งเหล่านี้ทำได้ง่าย จากนั้น PR ของฉันก็ถูกรวมเข้าด้วยกัน

เริ่ม

คุณสามารถเริ่มต้นได้ง่ายๆ โดยเลือกบางอย่างที่จะเพิ่มและเริ่มทำงานกับมันได้ในหลายกรณี หากคุณมีคำถามหรือต้องการความช่วยเหลือเกี่ยวกับเรื่องนี้ ฟอรัมสนทนา MDN เป็นสถานที่ที่ดีในการโพสต์ MDN คือที่ที่ฉันไปเพื่อค้นหาข้อมูล สถานที่ที่ฉันส่งนักพัฒนาใหม่และนักพัฒนาที่มีประสบการณ์มาเหมือนกัน และจุดแข็งของมันคือความจริงที่ว่าเราทุกคนสามารถปรับปรุงให้ดีขึ้นได้

หากคุณไม่เคยทำ Pull Request ในโครงการมาก่อน เป็นสถานที่ที่เป็นกันเองมากในการประชาสัมพันธ์ครั้งแรก และอย่างที่ฉันได้แสดงให้เห็นแล้ว มีวิธีการมีส่วนร่วมที่ไม่ต้องเขียนโค้ดใดๆ เลย ตามที่ฉันหวังไว้ ทักษะที่มีค่ามากสำหรับโครงการเอกสารใดๆ คือ การเขียน การแก้ไข และการแปล เนื่องจากทักษะเหล่านี้สามารถช่วยให้เอกสารทางเทคนิคอ่านง่ายขึ้นและเข้าถึงได้สำหรับผู้คนทั่วโลกมากขึ้น