[How to] การเขียน Readme.md สำหรับการทำ Document ของ Software Open source

What is Readme.md ?

ปกติเวลาเปิดเข้าไฟล์หรือโฟลเดอร์ของโปรแกรม ที่โหลดมาจากอินเทอร์เน็ต ส่วนมากจะมีไฟล์ชื่อ Readme.md ติดมาด้วย และนอกจากนั้นเราอาจจะพบเจอในพวก Lirbraly Open source เวลาที่ต้องโหลดมาเพื่อเขียน สำหรับหน้าตาของ Read.md ก็จะเป็นแบบนี้

ซึ่งที่เราเห็นนี้จะเป็นหลังจากการแปลงสัญญาลักษณ์ในการเขียน Readme.md แล้วหรือที่เขาเรียกว่า Markdown มาเป็นข้อความที่คนทั่วไปอ่านเข้าใจแบบด้านบน ส่วนการเขียน หรือรูปแบบการวางองค์ประกอบ Readme.md นั้นไม่ตายตัวแต่ถ้าพูดในแง่มุมของการพัฒนา Software แล้วเราก็จะมีองค์ประกอบตามตัวอย่างด้านบน คือ Title, Installation, Simple code or How to use it, Contributors (ถ้าพัฒนาคนเดียวก็ไม่จำเป็นต้องมี) และ License

What does Readme.md do ?

หน้าที่ของการเขียน Readme.md ในแง่ของการพัฒนาโปรแกรมนั่นเป็นสิ่งที่สำคัญมากโดยเฉพาะ Open source เพราะมันช่วยให้คนที่เข้ามาใช้งานระบบหรือ API หรือ Library เข้าใจว่าระบบของเราทำอะไร ใช้ยังไง และอีกหน้าที่นึงที่คนส่วนใหญ่มักจะทำกันคือ Documentation ของตัวระบบ

What is Markdown language ?

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

ดังนั่นเดียวเราจะมาเรียนรู้วิธีการเขียนฉบับพื้นฐานกันเพื่อช่วยให้การพัฒนา Software แบบ Open source นั้น ให้คนอื่นสามารถเข้าใจระบบเราและใช้งานเป็น

Let get started with Markdown language

เดี๋ยวเราจะมาเริ่มวิธีการเขียน Markdown กันซึ่งก็จะเป็นสัญญาลักษณ์พื้นๆ ที่ถ้าอ่านจบก็สามารถนำไปทำ Document สวยๆ สำหรับระบบได้เลยครับ

Headers — ใช้ในการเขียนหัวข้อซึ่งหลักๆ จะมีอยู่ 6 ระดับไล่จาก 1–6 หรือใหญ่ไปเล็ก

Emphasis — สำหรับจัดการข้อความตัวเอียงและหนา

Lists — สำหรับการเขียนหัวข้อมีทั่งแบบตัวเลขและแบบวงกลมทั่วไป

Images — ไว้แสดงผลรูปภาพจากลิ้งข้างนอก

Links — ไว้แปะลิ้งเพื่อกดไปยังเว็บอื่นหรือเรียกว่า Hyper links

Block quotes — สำหรับใส่ข้อความในลักษณ์คำพูด

Black slash escapes — สำหรับแสดงสัญญาลักษณ์เช่น * หรืออื่นเพราะปกติแล้วมันถูกใช้ทำตัวหนาแต่ถ้าเราอยากจะแสดงผลเป็น * จริงๆ เราก็ทำได้แบบนี้

Tables — สำหรับสร้างตาราง

Codes — สำหรับแสดงผลหรือจัดฟอร์แมตโค้ด สำหรับอักษรตัวที่ใช้งานนั้นปุ่มจะอยู่ที่ตัวหนอน หรือตัวเปลี่ยนภาษาของ Windows และมันคนละแบบกับ Single quote

Checkbox — ไว้สำหรับทำตัวเลือกหรือติ๊กถูก

หลักๆ แล้วพื้นฐานของการนำไปเขียน Document แล้วเราก็จะใช้กันประมาณนี้ แต่อันที่จริงแล้วมันมีอีกหลายแบบและหลายสัญญาลักษณ์ให้ใช้งานมา เช่น Flowchart, LaTeX (การแสดงผลสัญญาลักษณ์ทางคณิตศาสตร์) สำหรับการเรียนเพิ่มเติม ผมขอแนะนำให้ลองอ่านเว็บ http://pandao.github.io/editor.md/en.html และสามารถลองเขียนแบบออนไลน์ได้เลย ซึ่งเว็บนี้เขาก็ Support หลายฟอร์แมตอยู่เหมือนกัน

สำหรับบทความนี้คงจะหมดเท่านี้ ไว้เจอกันใหม่ตอนหน้า จะหาเทคนิคการพัฒนา Software มาฝากันอีกครับ

Have a question?

Drop us a line and we will get back to you