ไฟล์ README คืออะไร และวิธีการใช้งานอย่างถูกต้อง

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

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

ไฟล์ README คืออะไรกันแน่?

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

ไฟล์ประเภทนี้สามารถบันทึกได้ในรูปแบบต่างๆ รูปแบบข้อความ: จากคลาสสิก readme.txt (ข้อความธรรมดา) สูงสุด ไฟล์ readme.doc, readme.1st หรือส่วนขยายที่พบได้ไม่บ่อยนัก เช่น . ฉันรูปแบบเฉพาะมักจะถูกปรับให้เข้ากับ... ระบบปฏิบัติการและโปรแกรมที่จะใช้แสดงผลเพื่อให้ผู้ใช้ทุกคนสามารถเปิดและอ่านไฟล์ได้โดยไม่มีปัญหาใดๆ

ในปัจจุบัน โดยเฉพาะในโครงการซอฟต์แวร์และที่เก็บโค้ด รูปแบบที่พบได้บ่อยที่สุดคือ README.mdนามสกุลไฟล์ .md บ่งบอกว่าไฟล์นั้นถูกเขียนด้วยภาษาโปรแกรม MarkdownHTML เป็นภาษามาร์กอัปที่ง่ายมาก ซึ่งช่วยให้คุณแปลงข้อความให้เป็น HTML โดยใช้สัญลักษณ์เพียงไม่กี่ตัวในการจัดรูปแบบ ทำให้การจัดรูปแบบเนื้อหาทำได้ง่ายขึ้น อ่านง่ายทั้งในรูปแบบดิบและรูปแบบที่แสดงผลบนเว็บนอกเหนือจากการอนุญาตให้ใส่หัวเรื่อง รายการ ลิงก์ ตาราง รูปภาพ และอื่นๆ ได้โดยไม่ยุ่งยากแล้ว

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

ในแวดวงข้อมูล เช่น ในคลังข้อมูล เป็นเรื่องปกติมากที่ไฟล์ README (บางครั้งอยู่ในรูปแบบอื่น) จะเป็น readme.txt) เก็บรวบรวม ข้อมูลทั่วไป, ผู้แต่ง, คำสำคัญ, ขอบเขตทางภูมิศาสตร์และช่วงเวลา, ใบอนุญาตการใช้งาน และวิธีการวิจัย ใช้ในการสร้างหรือรวบรวมข้อมูล รวมถึง ซอฟต์แวร์ที่แนะนำสำหรับการทำงานร่วมกับพวกเขา.

ประวัติโดยย่อและการใช้งานมาตรฐานของไฟล์ README

แม้ว่าในปัจจุบันเรามักจะเชื่อมโยงไฟล์ README กับแพลตฟอร์มอย่าง GitHub แต่ธรรมเนียมการใส่ไฟล์ README ในแพ็กเกจซอฟต์แวร์นั้นมีมาตั้งแต่สมัยโบราณ หลายทศวรรษที่แล้วมีตัวอย่างที่บันทึกไว้ซึ่งมีอายุย้อนไปถึง ช่วงกลางทศวรรษ 70ในขณะที่โปรแกรมต่างๆ ได้ถูกแจกจ่ายพร้อมเอกสารขนาดเล็กที่อธิบายเนื้อหาและวิธีการใช้งานอยู่แล้ว

เมื่อเวลาผ่านไป การปฏิบัติเช่นนี้ก็กลายเป็นที่ยอมรับจนกระทั่งในที่สุด... มาตรฐานการเขียนโค้ดของ GNU (ตามมาตรฐานการเขียนโค้ดของ GNU) ไฟล์ README ถือว่าเป็น ความต้องการมาตรฐานเหล่านี้มีอิทธิพลอย่างมากต่อระบบนิเวศของซอฟต์แวร์โอเพนซอร์ส และมีส่วนทำให้ไฟล์ README กลายเป็นสิ่งจำเป็นเกือบจะขาดไม่ได้ในซอฟต์แวร์ระดับมืออาชีพทุกแพ็กเกจ

เมื่อเว็บกลายเป็น แพลตฟอร์มมาตรฐานสำหรับการเผยแพร่ซอฟต์แวร์หลายโครงการเริ่มย้ายข้อมูลบางส่วนที่เคยอยู่ในไฟล์ README (คู่มือ ใบอนุญาต ข่าวสาร ฯลฯ) ไปไว้ในเว็บไซต์ วิกิ หรือแหล่งข้อมูลอื่น ๆ แพ็คเกจไฟล์ tarball ของซอร์สโค้ดถึงกระนั้น ไฟล์ README ก็ไม่เคยหายไป: ในหลายกรณีมันยังคงอยู่เช่นเดิม สรุปข่าวท้องถิ่นถึงแม้ว่าบางครั้งข้อมูลอาจยังไม่ครบถ้วนสมบูรณ์เมื่อเทียบกับเอกสารออนไลน์ก็ตาม

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

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

ไฟล์ทั่วไปที่แนบมาพร้อมกับไฟล์ README

ในโครงการที่ปฏิบัติตามมาตรฐานต่างๆ เช่น มาตรฐาน Gnits หรือที่สร้างขึ้นด้วยเครื่องมือต่างๆ เช่น GNU Autotoolsนอกจากไฟล์ README หลักแล้ว มักพบไฟล์ข้อความอื่นๆ ที่ให้ข้อมูลเพิ่มเติมเกี่ยวกับโครงการ ตัวอย่างไฟล์ที่พบบ่อยที่สุด ได้แก่:

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

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

บทบาทของไฟล์ README บน GitHub และแพลตฟอร์มที่คล้ายคลึงกัน

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

GitHub จะจดจำไฟล์ README โดยอัตโนมัติเมื่อวางไว้ในตำแหน่งที่กำหนดในที่เก็บข้อมูล หากคุณวางไว้ในโฟลเดอร์... .githubใน ไดเรกทอรีราก หรือในโฟลเดอร์ docsแพลตฟอร์มตรวจจับได้แล้ว และ แสดงให้เห็นอย่างเด่นชัด สำหรับผู้เข้าชม เมื่อมีไฟล์ README หลายไฟล์ GitHub จะปฏิบัติตาม ลำดับความสำคัญ: การค้นหาครั้งแรกใน .githubจากนั้นที่ราก และสุดท้ายที่ docs.

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

เมื่อเปิดดูไฟล์ README (หรือไฟล์ .md ใดๆ) บน GitHub แพลตฟอร์มจะสร้างไฟล์โดยอัตโนมัติ สารบัญ โดยอิงจากชื่อเอกสาร คุณสามารถดูสารบัญนี้ได้โดยคลิกที่ไอคอน "โครงร่าง" ซึ่งจะช่วยให้การค้นหาข้อมูลในไฟล์ README ที่ยาวและมีหลายส่วนทำได้ง่ายขึ้นมาก

GitHub ยังอนุญาตอีกด้วย เชื่อมโยงโดยตรงไปยังส่วนต่างๆ ที่ต้องการแต่ละหัวข้อจะสร้างจุดเชื่อมโยงโดยอัตโนมัติ เพียงแค่เลื่อนเมาส์ไปวางเหนือชื่อหัวข้อ ไอคอนลิงก์ก็จะปรากฏขึ้น วิธีนี้ช่วยให้คุณสามารถแชร์ URL ที่ชี้ไปยังส่วนเฉพาะของไฟล์ README ที่คุณต้องการเน้น (ตัวอย่างเช่น ส่วนการติดตั้งหรือส่วนการมีส่วนร่วม)

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

รูปแบบและการเชื่อมโยงภายในไฟล์ README

เพื่อให้ README ดูแลรักษาง่ายและใช้งานได้ดีทั้งบน GitHub และเวอร์ชันที่คัดลอกมาใช้งาน ขอแนะนำให้ใช้ ลิงก์ที่เกี่ยวข้อง และเส้นทางของรูปภาพจะสัมพันธ์กับตำแหน่งไฟล์ที่รูปภาพนั้นอยู่ ตัวอย่างเช่น หากคุณมีไฟล์ README อยู่ในไดเร็กทอรีหลักและเอกสารอีกไฟล์หนึ่ง docs/CONTRIBUTING.mdลิงก์ภายในไฟล์ README จะมีลักษณะดังนี้: (docs/CONTRIBUTING.md).

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

เป็นสิ่งสำคัญที่ ข้อความลิงก์ ควรเขียนลิงก์ไว้ในบรรทัดเดียว เพราะการแบ่งลิงก์ออกเป็นหลายบรรทัดอาจทำให้เกิดปัญหาได้ นอกจากนี้ ควรหลีกเลี่ยงการสร้างลิงก์แบบสัมบูรณ์ไปยังไฟล์ภายในของที่เก็บข้อมูล เนื่องจากอาจใช้งานไม่ได้หาก URL หลักเปลี่ยนแปลงหรือมีการสร้าง fork ขึ้นมา

ในส่วนของขอบเขตของเอกสารนั้น ควรจำไว้ว่าไฟล์ README ควรมีเนื้อหาเพียงเท่านี้ ข้อมูลสำคัญที่จะช่วยให้คุณเริ่มต้นใช้งานและมีส่วนร่วมได้ สำหรับโครงการ สำหรับการจัดทำเอกสารอย่างละเอียด (คู่มือผู้ใช้ คู่มือ API ฉบับสมบูรณ์ ฯลฯ) การใช้ จะทำให้ดูเรียบร้อยกว่า วิกิพีเดีย หรือระบบเอกสารแยกต่างหาก โดยเชื่อมโยงจากไฟล์ README เอง

จุดประสงค์ที่แท้จริงของไฟล์ README คืออะไร?

นอกเหนือจากทฤษฎีแล้ว ไฟล์ README ยังทำหน้าที่ในทางปฏิบัติดังนี้ แนวทางเบื้องต้นและจุดอ้างอิงเอกสารนี้ไม่ได้มีจุดประสงค์เพื่อทดแทนเอกสารทางการที่มีรายละเอียดมากมาย แต่มีจุดประสงค์เพื่อนำเสนอคำอธิบายที่เป็นระเบียบและใช้งานได้จริงเกี่ยวกับประเด็นสำคัญที่สุดของโครงการ

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

ในโครงการที่ทำร่วมกัน โดยเฉพาะในทีมขนาดใหญ่หรือชุมชนโอเพนซอร์ส ไฟล์ README แทบจะเป็นสิ่งสำคัญอย่างยิ่ง ส่วนประกอบโครงสร้างพื้นฐานการสื่อสารเอกสารนี้มีไว้เพื่อปรับความคาดหวังให้สอดคล้องกัน ระบุระดับความพร้อมของโครงการ กำหนดบทบาทการมีส่วนร่วมของแต่ละบุคคล และชี้แจงว่าได้รับการสนับสนุนอะไรบ้าง (ถ้ามี)

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

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

เมื่อใดจึงเหมาะสมที่จะสร้างไฟล์ README?

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

ตัวอย่างบางส่วนที่ไฟล์ README มีประโยชน์เป็นพิเศษ ได้แก่ โครงการเว็บหรือการเขียนโปรแกรมซึ่งควรอธิบายถึงข้อกำหนด กระบวนการพัฒนา คำสั่งเริ่มต้น และสภาพแวดล้อมการทำงาน นอกจากนี้ยังน่าสนใจมากใน... โฟลเดอร์ที่มีข้อมูลสำคัญเพื่อชี้แจงว่าข้อมูลนั้นแสดงถึงอะไร มีที่มาอย่างไร และมีข้อจำกัดอะไรบ้าง

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

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

ไฟล์ README ที่ดีควรมีข้อมูลอะไรบ้าง?

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

อย่างน้อยที่สุด คลังเก็บข้อมูลและแพ็กเกจที่มีเอกสารประกอบอย่างดีส่วนใหญ่จะรวมถึงสิ่งต่อไปนี้ ชื่อโครงการ, คำอธิบายโดยย่อเกี่ยวกับวัตถุประสงค์สรุปเนื้อหาของคลังข้อมูล คำแนะนำสำหรับการใช้งานหรือการติดตั้ง และข้อกำหนดที่จำเป็น (การพึ่งพาของโปรแกรมอื่น เวอร์ชันภาษาขั้นต่ำ ระบบปฏิบัติการ ฯลฯ)

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

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

ลำดับการจัดเรียงยังมีผลต่อความอ่านง่ายด้วย: ข้อมูลที่สำคัญที่สุด (โครงการคืออะไร มีไว้เพื่ออะไร และใช้งานอย่างไร) ควรปรากฏเป็นอันดับแรก ในตอนต้นของเอกสารโดยจะเก็บรายละเอียดรองลงมา ข้อมูลเครดิตเพิ่มเติม หรือบันทึกทางประวัติศาสตร์ไว้ทีหลัง วิธีนี้จะช่วยให้ผู้ที่แค่ดูผ่านๆ สามารถเข้าใจภาพรวมได้อย่างรวดเร็ว

เนื้อหาทั่วไปของไฟล์ README ในซอฟต์แวร์

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

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

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

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

ไฟล์ README ในฐานะเครื่องมือสื่อสารบน GitHub

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

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

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

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

GitHub ยังมีเครื่องมืออำนวยความสะดวกเฉพาะบางอย่างที่เกี่ยวข้องกับไฟล์ README เช่น การสร้างดัชนีโดยอัตโนมัติ รองรับป้ายและไอคอน และอนุญาตให้คุณแทรกรูปภาพ GIF หรือวิดีโอเพื่อแสดงผลงานโครงการ หากใช้ให้มีประสิทธิภาพ องค์ประกอบเหล่านี้จะช่วยให้ไฟล์ README มีประสิทธิภาพมากขึ้น น่าดึงดูดยิ่งขึ้นและใช้งานง่ายขึ้น.

วิธีการจัดโครงสร้างและปรับปรุงไฟล์ README ของคุณ

เมื่อวิเคราะห์คลังเก็บซอฟต์แวร์ยอดนิยม (ตัวอย่างเช่น โครงการจากองค์กรเทคโนโลยีขนาดใหญ่หรือหน่วยงานด้านอวกาศ) พบว่าไฟล์ README ของคลังเหล่านั้นมักมีลักษณะร่วมกันหลายประการ รูปแบบทั่วไปถึงแม้ว่าแต่ละโครงการจะรักษาเอกลักษณ์ด้านภาพและเนื้อหาของตนเองไว้ก็ตาม

เป็นเรื่องปกติที่จะพบเห็น ชื่อเรื่องที่ชัดเจนและภาพปกที่เป็นไปได้ (เช่น โลโก้หรือแบนเนอร์สำหรับโครงการ) ตามด้วยป้ายต่างๆ ที่สรุปสถานะของโครงการ ใบอนุญาต เวอร์ชันปัจจุบัน หรือสถานะการทดสอบ จากนั้นมักจะมี คำอธิบายโครงการโดยจะมีส่วนที่แสดงสถานะ (เสถียร อยู่ระหว่างการพัฒนา ทดลอง ฯลฯ) และส่วนที่มีตัวอย่างหรือภาพหน้าจอ

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

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

เทคนิคที่คนไม่ค่อยพูดถึงคือ การเขียนโดยนึกถึงใครบางคนอยู่เสมอ เขาไม่รู้อะไรเลยเกี่ยวกับโครงการนี้นั่นหมายถึงการหลีกเลี่ยงการตั้งสมมติฐานเกี่ยวกับความรู้เดิม การใช้ภาษาที่ชัดเจนและตรงไปตรงมา และการชี้แจงคำศัพท์ทางเทคนิคในครั้งแรกที่ปรากฏ และแน่นอนว่า ต้องอัปเดตไฟล์ README ทุกครั้งที่มีการเปลี่ยนแปลงที่เกี่ยวข้องกับโครงการ

ลิขสิทธิ์ การมีส่วนร่วม และความเป็นเจ้าของผลงาน

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

วิธีปฏิบัติที่พบได้บ่อยที่สุดคือการใช้ใบอนุญาตที่เป็นที่รู้จักกันดี (เช่น MIT, Apache, GPL, Creative Commons สำหรับเอกสารประกอบ ฯลฯ) และเชื่อมโยงจากไฟล์ README ไปยังไฟล์ LICENSE หรือ COPYING ของที่เก็บโค้ด วิธีนี้จะทำให้ผู้ที่สนใจทราบได้ทันทีว่าพวกเขาสามารถทำอะไรกับโค้ดได้บ้าง และมีข้อผูกพันอะไรบ้าง (เช่น การอ้างอิงแหล่งที่มา การแบ่งปันอย่างเท่าเทียมกัน ข้อจำกัดความรับผิด ฯลฯ)

อีกหนึ่งองค์ประกอบสำคัญในไฟล์ README ที่สมบูรณ์คือ... คู่มือการบริจาคส่วนนี้อธิบายวิธีการที่ผู้อื่นสามารถมีส่วนร่วมในโครงการได้: แนวทางการเขียนโค้ด กระบวนการส่งคำขอแก้ไข (pull request) วิธีการรายงานข้อผิดพลาด ประเภทของการมีส่วนร่วมที่ยอมรับได้ และสถานที่ประสานงาน บางครั้งข้อมูลนี้จะอยู่ในไฟล์ CONTRIBUTING.md แยกต่างหาก ซึ่งเชื่อมโยงมาจากไฟล์ README

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

สุดท้ายนี้ ควรกล่าวอธิบายเพิ่มเติมสักสองสามบรรทัด วิธีขอความช่วยเหลือ และมีช่องทางใดบ้าง เช่น ปัญหาบน GitHub, ฟอรัม, รายชื่อผู้รับจดหมาย, แชท ฯลฯ หากโครงการไม่มีการให้การสนับสนุนอย่างเป็นทางการ ก็ควรระบุให้ชัดเจนเพื่อหลีกเลี่ยงความเข้าใจผิด

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