ระยะปัจจุบัน:
โปรแกรม Season of Docs ปี 2020 จบลงแล้วเมื่อวันที่ 15 มีนาคม 2021 ดูไทม์ไลน์
หน้านี้จะมีหลักเกณฑ์สำหรับนักเขียนด้านเทคนิคเกี่ยวกับวิธีการสร้างรายงานโปรเจ็กต์เมื่อคุณทำงานสำหรับ "เอกสารประจำฤดูกาลของปีนี้" เสร็จแล้ว
กำลังส่งรายงานโปรเจ็กต์
เมื่อเปิดช่วงสรุปโปรเจ็กต์ คุณจะส่งรายงานโปรเจ็กต์ได้โดยการกรอกแบบฟอร์มที่มีอยู่ในส่วนการสรุปโปรเจ็กต์ของคู่มือทางเทคนิคสำหรับผู้เขียน
ข้อมูลที่จะรวมไว้ในรายงานโครงการ
ส่วนนี้อธิบายประเภทข้อมูลที่คุณสามารถใส่ในรายงานโครงการ แบบฟอร์มรายงานโครงการจะมีช่องข้อความอิสระ และคำถามแบบหลายตัวเลือก
ลิงก์ไปยังงานของคุณ
ระบุลิงก์ที่ชี้ไปยังคำอธิบายของงานที่คุณทำ
ลิงก์ควรชี้ไปยังเอกสารที่มีคำอธิบายสั้นๆ เกี่ยวกับงานที่ทำเสร็จแล้ว เอกสารประกอบที่โปรเจ็กต์โอเพนซอร์สผสานรวมเข้ากับที่เก็บ สรุปสถานะปัจจุบันของโปรเจ็กต์ และรายการความท้าทายและการเรียนรู้
ลิงก์ดังกล่าวจะปรากฏในผลลัพธ์ของซีซันของเอกสารที่เผยแพร่ในเว็บไซต์ ผลลัพธ์ที่เผยแพร่จะแสดงงานที่คุณทำเสร็จสมบูรณ์ระหว่างโปรแกรมนี้ ผลลัพธ์ที่เผยแพร่แล้วยังเป็นวิธีที่ดี ในการกลับไปดูงานซึ่งเป็นส่วนหนึ่งของเรซูเม่ด้วย
คุณควรแชร์ลิงก์กับที่ปรึกษาและขอการตรวจสอบก่อนที่จะส่งรายงานโปรเจ็กต์
ข้อกำหนดสำหรับรายงานโปรเจ็กต์
โปรดคำนึงถึงข้อกำหนดต่อไปนี้
- เนื้อหาที่ลิงก์ต้องช่วยให้ระบุงานที่คุณทำเสร็จในระหว่างฤดูกาลของเอกสารได้อย่างง่ายดาย กล่าวคือ การเปลี่ยนแปลงที่คุณทำหรือเอกสารใหม่ที่คุณเขียน
- งานควรอยู่ในที่ที่มีเสถียรภาพ คุณเปลี่ยน URL ไม่ได้หลังจากส่งแล้ว
บุคคลอื่นควรใช้เนื้อหาในลิงก์ (หรืออ้างอิงจาก) เป้าหมายของลิงก์เพื่อต่อยอดงานของคุณ
- หากงานของคุณเสร็จสมบูรณ์แล้ว บุคคลอื่นควรสามารถใช้งานได้
- หากงานของคุณยังไม่เสร็จ 100% ก็ควรบอกให้ชัดเจนว่างานที่เหลือต้องทำอะไรบ้าง
ตัวอย่างที่ดีในการอธิบายผลงานของคุณ
คุณไม่จำเป็นต้องทำทั้งหมด (หรือทั้งหมด) เลย แต่ก็มีบางวิธีที่ช่วยให้คุณทำตามข้อกำหนดได้ ดังนี้
สร้างบล็อกโพสต์หรือหน้าเว็บหรือ GitHub แบบสาธารณะที่อธิบายผลงานที่คุณทำไว้ รวมถึงลิงก์ไปยังคอมมิตที่คุณสร้างและที่เก็บที่คุณดำเนินการ หากยังมีงานที่ต้องทำในโปรเจ็กต์ ให้ใส่รายละเอียดงานนั้นด้วย คุณยังสามารถแชร์ไฮไลต์หรือผลงานที่ท้าทายได้ด้วย
นี่คือตัวเลือกที่ดีที่สุดเพราะว่าคุณจะสามารถรวมข้อมูลจำนวนมากได้โดยง่าย วิธีนี้ดีเพราะจะแสดงอย่างชัดเจนถึงสิ่งที่คุณทำ และช่วยให้ผู้อื่นใช้และทำความเข้าใจข้อมูลที่คุณร่วมทำได้ง่าย
หากใช้ GitHub และงานทั้งหมดอยู่ภายใต้คำขอพุลเดียว คุณจะใช้ลิงก์นั้นได้
- ตรวจสอบว่าคำอธิบายการดึงคำขอมีรายละเอียดแล้ว
- ตรวจสอบว่าคำอธิบายระบุอย่างชัดเจนว่าเป็นผลงานสำหรับซีซันของเอกสาร
- หากการดึงคำขอต้องมีการดำเนินการเพิ่มเติมหลังจากซีซันของเอกสารสิ้นสุดลง โปรดตรวจสอบว่าซีซันสุดท้ายของเอกสารคอมมิตทราบถึงข้อเท็จจริงนี้แล้ว
- วิธีการสร้างรายงานโปรเจ็กต์มีประโยชน์ในการมีบันทึกการเปลี่ยนแปลง รายการคอมมิต และความคิดเห็นในรีวิวทั้งหมดในที่เดียว
หากที่เก็บ GitHub มีไว้สำหรับ Season of Docs ให้เพิ่มไฟล์ README ที่มีรายละเอียดของงาน
สร้างโฟลเดอร์สาธารณะใน Google ไดรฟ์และใส่แพตช์ทั้งหมดที่คุณสร้างไว้
สร้างสเปรดชีตสาธารณะด้วย Google ชีตแล้วระบุคอมมิตทั้งหมด
ลิงก์ไปยังปัญหาเดียวในเครื่องมือติดตามปัญหาสาธารณะ ที่มีการอ้างอิงที่ชัดเจนเกี่ยวกับงานของคุณและเรื่องอื่นๆ ที่เหมาะสม ปัญหาควรติดตาม งานทั้งหมดที่คุณทำ ตรวจสอบว่าปัญหาแสดงคอมมิตทั้งหมดหรือ ค้นหาคอมมิตได้โดยง่ายด้วยวิธีอื่น
ลิงก์ไปยังการเปลี่ยนแปลงแบบรวมหรือบริบทของการเปลี่ยนแปลง อย่าลืมใส่ส่วนหัวที่มีชื่อโปรเจ็กต์การเขียนเชิงเทคนิคและตัวตนของคุณ เพื่อให้เป็นประโยชน์ต่อผู้อื่น
ตัวอย่างที่ไม่ดีในการอธิบายผลงานของคุณ
สิ่งที่ไม่ควรทำ
- ลิงก์ไปยังไฟล์ tarball หรือ zip ที่มีซอร์สโค้ดของโปรเจ็กต์ทั้งหมดหรือไดเรกทอรีการทำงาน
- ลิงก์ไปยังที่เก็บต้นทางหลักของโปรเจ็กต์ ตัวอย่างเช่น หากคุณใช้ cpython ลิงก์นี้ก็จะไม่มีประโยชน์: https://github.com/python/cpython
- ลิงก์ไปยังการโคลนของที่เก็บต้นทางของโปรเจ็กต์ ซึ่งทำให้ยากที่จะทราบว่าการเปลี่ยนแปลงของคุณเป็นอย่างไร เนื่องจากงานของคุณจะปนกับงานของคนอื่น
- ลิงก์ไปยังคำอธิบายโปรเจ็กต์ของคุณในเว็บไซต์ Season of Docs
สำหรับ Mentor
โปรดช่วยผู้เขียนด้านเทคนิคสร้างรายงานโปรเจ็กต์ที่เหมาะสม คุณจะต้องดำเนินการนี้ก่อนสร้างการประเมินงานของนักเขียนด้านเทคนิคด้วยตนเอง
โปรดตรวจสอบสิ่งต่อไปนี้
- ข้อมูลที่ส่งต้องเป็นไปตามข้อกำหนดที่อธิบายไว้ข้างต้น
- ข้อมูลที่ส่งจะต้องมีคำอธิบายงานที่ทำ ข้อกำหนดที่พอใจ และเหตุผลของการตัดสินใจที่เจาะจง
เป้าหมายของ Season of Docs ไม่ใช่ว่านักเขียนด้านเทคนิคจะเลิกใช้เอกสารจำนวนมาก งานดังกล่าวอาจมีประโยชน์กับโครงการโอเพนซอร์สที่โฮสต์