สร้างรายงานโปรเจ็กต์

ระยะปัจจุบัน:
โปรแกรม 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 ไม่ใช่ว่านักเขียนด้านเทคนิคจะเลิกใช้เอกสารจำนวนมาก งานดังกล่าวอาจมีประโยชน์กับโครงการโอเพนซอร์สที่โฮสต์