nitip.at

nitip.at

readme ไปทำไม?

readme ไปทำไม?

Nitipat Lowichakornthikun's photo
Nitipat Lowichakornthikun
·Dec 19, 2018·

1 min read

ปกติการพัฒนาซอฟแวร์ทั่วไปสิ่งนึงที่เมื่อเราได้มีโอกาสไปเจอกับโปรเจกต์ต่าง ๆ เราต้องเจอไฟล์ readme ซึ่งเมื่อเราลองมาดูกันที่โปรเจกต์ที่เป็น Open source ดัง ๆ จะพบว่าทุกโปรเจกต์ต้องมีไฟล์นี้อยู่เสมอ โดยมาในหลากหลายนามสกุล เช่นreadme.doc (ไฟล์ Word format), readme.txt , readme.md (ไฟล์ในรูปแบบ Markdown) ทำให้เราเห็นว่ามันเป็นสิ่งสำคัญมากที่แต่ละโปรเจกต์ต้องมีอยู่

  • สำหรับใครที่งงว่า markdown คืออะไร? ให้ดูต่อได้จากลิงค์ด้านล่างเลย

Markdown คืออะไร มาหัดเขียน Markdown กันเถอะ
Markdown มันคือภาษา ๆ หนึ่งนั่นแหละที่คนสร้างสร้างขึ้นเพื่อให้มนุษย์สามารถอ่านได้เข้าใจง่าย ๆ…
medium.com

ถ้ามันสำคัญขนาดนี้ทำไมเรายังไม่ทำล่ะ?

อะไรจุดประสงค์หลัก?

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

เมื่อไรที่ต้องมี?

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

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

หน้าตาของ readme ที่ดี?

นี่คือตัวอย่างที่ดีในการประกอบไปด้วยข้อมูลของโปรเจกต์เรา โดย Billie Thompson

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

Choose an open source license
Non-judgmental guidance on choosing a license for your open source project
choosealicense.com

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

อ้างอิง

About READMEs - User Documentation
You can add a README file to your repository to tell other people why your project is useful, what they can do with…
help.github.com

A crash course on writing a better README
In the wake of the Hacktoberfest we’ve seen a huge growth in open source contributions. The open-source community has…
hackernoon.com

Make a README
Learn how to make a great README for your programming project, and use the editable template to get started.
makeareadme.com

 
Share this