Merging duplicated or closely related small documentation files together

[bact]

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

กลุ่มที่ 1: ไฟล์ LICENSE

• https://github.com/PyThaiNLP/pythainlp/blob/dev/LICENSE
• https://github.com/PyThaiNLP/pythainlp/blob/dev/LICENSE.txt

กลุ่มนี้น่าจะเหลือไฟล์เดียวได้เลย โดยเสนอให้เลือกลบ LICENSE.txt และคง LICENSE ไว้ เนื่องจากเป็นไฟล์ที่ GitHub อ่านออก (มีแสดง panel สรุปสัญญาอนุญาตให้)

กลุ่มที่ 2: ไฟล์ README

• https://github.com/PyThaiNLP/pythainlp/blob/dev/README.md
• https://github.com/PyThaiNLP/pythainlp/blob/dev/README.rst
• https://github.com/PyThaiNLP/pythainlp/blob/dev/README-pythainlp.md

กลุ่มนี้เข้าใจว่าที่มี 3 ไฟล์ เพราะบางอันใช้กับ PyPI บางอันใช้กับ GitHub
แต่ในทางปฏิบัติ หากต้องการรวมเป็นไฟล์เดียว เราสามารถตั้งค่าใน setup.py ไปที่ชื่อไฟล์ที่เราต้องการได้

เสนอให้รวมเป็นไฟล์เดียว

กลุ่มที่ 3: ไฟล์ CONTRIBUTORS

• https://github.com/PyThaiNLP/pythainlp/blob/dev/CONTRIBUTING.md
• https://github.com/PyThaiNLP/pythainlp/blob/dev/AUTHORS.rst
• https://github.com/PyThaiNLP/pythainlp/blob/dev/References.md

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

โดยเสนอให้ในไฟล์ใหม่ แบ่งเป็น 3 หัวข้อ คือ

1. จะร่วมลงแรงกับโครงการได้อย่างไร (CONTRIBUTING.md)
2. ทีมงานและเครดิต (AUTHORS.rst)
3. อ้างอิง (References.md)

การรวม

หากเห็นด้วยกับแนวทางการรวมนี้ (ไม่จำเป็นต้องรวมทุกกลุ่ม) ผมยินดีจะรวมให้ครับ แต่ก่อนลงมือ ขอปรึกษาว่า ไฟล์ที่รวมกัน อยากให้ฟอร์แมตไหน RST หรือ Markdown ครับ

ดูเปรียบเทียบ 2 ฟอร์แมตนี้ได้ที่

• https://gist.github.com/dupuy/1855764
• http://www.zverovich.net/2016/06/16/rst-vs-markdown.html

(รวมๆ คือ Markdown เรียบง่ายกว่า ส่วน RST มีส่วนขยายที่เหมาะกับการเขียน technical document มากกว่า)

[wannaphong]

ขอตอบในส่วนแต่ละกลุ่มไฟล์นะครับ

กลุ่มที่ 1: ไฟล์ LICENSE
เห็นด้วยครับ เพราะเหมือนว่า GitHub จะอ่านจากไฟล์ LICENSE อย่างเดียวนะครับ

กลุ่มที่ 2: ไฟล์ README

อันนี้ตอนแรกมีเพียงไฟล์ README.rst กับ README.md ต่อมาผมแยกไฟล์ README-pythainlp.md ออกจากไฟล์ README.md เพื่อนำไปแสดงผลใน pypi ส่วน README.md เป็นไฟล์หน้าหลักสำหรับแสดงแนะนำโครงการใน GitHub เพราะใน GitHub branche ตั้งต้นเป็น dev เป็นเวชั่นใหม่ที่กำลังพัฒนา ซึ่งไม่ใช่เวชั่นสำหรับใช้งานจริงครับ

ผมคิดว่าควรจะลบไฟล์ README.rst ทิ้ง และเปลี่ยนชื่อไฟล์ README-pythainlp.md -> README-pypi.md เพื่อลดความสับสนครับ

กลุ่มที่ 3: ไฟล์ CONTRIBUTORS

เห็นด้วยครับ

ส่วนการรวม ผมคิดว่าควรจะเลือกฟอร์แมต Markdown ครับ เน้นความเรียบง่ายเป็นหลักครับ

[bact]

จะลองทำตามที่แนะนำครับ ขอบคุณครับ