กำไร:
- ความสามารถในการสร้าง README เอกสาร และบันทึกการเปลี่ยนแปลงแบบร่างตามกลุ่มเป้าหมายและแหล่งที่มาด้วย AI
- ความสามารถในการแยกเลเยอร์ 'อะไร/อย่างไร' และ 'ทำไม' ในเอกสารประกอบ และเพิ่ม 'ทำไม' ในฐานะมนุษย์
- การตรวจสอบขั้นตอนการติดตั้งโดยการรันด้วยตนเองและทำให้เอกสารเป็นส่วนหนึ่งของการเปลี่ยนแปลงโค้ด
ส่วนที่ละเลยบ่อยที่สุดของซอฟต์แวร์แต่ยาวนานที่สุดคือเอกสารประกอบ รหัสสามารถอ่านได้แม้หลังจากผ่านไปหลายเดือน คนเขียนมันหายไป บริบทถูกลืม และเหลือเพียงสิ่งที่เขียนเท่านั้น README ที่ดี (เอกสารเบื้องต้นที่อธิบายว่าโปรเจ็กต์คืออะไร รวมถึงวิธีติดตั้งและรัน) ความคิดเห็นเกี่ยวกับโค้ดอธิบาย และเอกสาร API ที่ทันสมัย (ข้อมูลอ้างอิงที่อธิบายวิธีใช้อินเทอร์เฟซ) จะกำหนดความเร็วของทีมโดยตรง AI ดึง “ความเหนื่อยล้าในการเขียน” ออกจากเอกสารได้มาก แต่มันมาพร้อมกับกับดัก: AI สามารถอนุมานได้จากโค้ดว่ามันทำอะไร แต่มักจะไม่รู้ว่าทำไมมันถึงเป็นเช่นนั้น
ในหน่วยนี้ คุณจะได้เรียนรู้วิธีสร้าง README ความคิดเห็นของโค้ด docstring (บล็อกความคิดเห็นที่เขียนต่อฟังก์ชัน/คลาส) เอกสาร API และบันทึกการเปลี่ยนแปลงด้วย AI และวิธีการรักษาส่วนที่มีค่าที่สุดของเอกสารอย่างมนุษย์มนุษย์: "ทำไม"
ความแตกต่างระหว่าง "อะไร" และ "ทำไม"
เอกสารมีสองชั้น อย่างแรกคืออะไร/อย่างไร: "ฟังก์ชันนี้เรียงลำดับรายการ", "เรียกใช้คำสั่งนี้เพื่อติดตั้ง" สิ่งเหล่านี้สามารถแยกได้จากโค้ดและโครงสร้าง AI เก่งที่นี่ ประการที่สอง ทำไม: "เหตุใดเราจึงให้บริการนี้แบบอะซิงโครนัสมากกว่าแบบซิงโครนัส", "เหตุใดค่าขีดจำกัดนี้จึงอยู่ที่ 30 วินาที", "เหตุใดเราจึงเลือกไลบรารีนี้เหนือไลบรารีอื่น" สิ่งเหล่านี้ไม่ได้เขียนไว้ในโค้ด มันเป็นผลผลิตของการตัดสินใจออกแบบ ข้อจำกัด และความเจ็บปวดในอดีต
AI ไม่รู้ว่า "ทำไม"; อย่างดีที่สุด เป็นการเดาที่สมเหตุสมผล—ซึ่งเป็นอันตราย เพราะเหตุผลที่ผิดนั้นแย่กว่าการไม่มีเหตุผลเลย ดังนั้นการแบ่งงานจึงชัดเจน: AI ร่าง "อะไร/อย่างไร" และเพิ่ม "ทำไม" ความคิดเห็นที่มีค่าที่สุดคือความคิดเห็นที่บอกว่าโค้ดไม่สามารถพูดได้
เคล็ดลับ: อย่าแสดงความคิดเห็นซ้ำในสิ่งที่โค้ดบอกอย่างชัดเจน (เช่น i = i + 1 // เพิ่ม i ทีละรายการ) บางครั้ง AI ก็มีความคิดเห็นที่ซ้ำซ้อนเช่นนี้ กำจัดพวกเขาและทุ่มเทพลังงานของคุณให้กับความคิดเห็นที่ "ทำไม"
ทีละขั้นตอน: การสร้างเอกสารด้วย AI
- ระบุกลุ่มเป้าหมาย “นักพัฒนาที่เพิ่งเริ่มต้น” “ทีมภายนอกที่จะใช้ API นี้” “ตัวฉันในอนาคต” — ผู้ชมจะเป็นผู้กำหนดโทนของภาษาและความลึก
- ให้แหล่งที่มา. เพิ่มโค้ดที่เกี่ยวข้อง README ที่มีอยู่ ตัวอย่างการใช้งานลงในพรอมต์ เอกสารที่ไม่มีแหล่งที่มาถือเป็นคำเชิญให้มีการประดิษฐ์
- โครงสร้างการจัดเก็บภาษี ส่วนมาตรฐานสำหรับ README (วัตถุประสงค์ การติดตั้ง การใช้งาน การกำหนดค่า การบริจาค) รูปแบบโปรเจ็กต์สำหรับ docstring
- ทำเครื่องหมายช่องว่าง "ทำไม" ขอให้ AI ทำเครื่องหมายการตัดสินใจโดยไม่ทราบเหตุผลว่า "ต้องการบันทึกย่อ 'ทำไม' ที่นี่"; จากนั้นคุณกรอกข้อมูลลงในช่องว่างเหล่านั้น
- ตรวจสอบ. รันขั้นตอนการติดตั้งจริง ลองโค้ดตัวอย่าง README ที่ใช้งานไม่ได้จะแย่ยิ่งกว่าไม่มี README เลย
มินิเคสสามอัน
กรณีที่ 1 — README เร่งการเริ่มต้นใช้งาน README ของเครื่องมือโอเพ่นซอร์สหายไป ผู้ร่วมให้ข้อมูลรายใหม่ประสบปัญหาในการติดตั้งเป็นเวลาเฉลี่ย 2 ชั่วโมง ทีมงานมอบสคริปต์การติดตั้งและ package.json ให้กับ AI และร่าง README ที่มีโครงสร้าง จากนั้นรันขั้นตอนด้วยตนเองบนเครื่องที่สะอาด และเพิ่มการขึ้นต่อกันสองรายการที่ขาดหายไป เวลาในการติดตั้งสำหรับผู้มีส่วนร่วมรายต่อๆ ไปลดลงเหลือเฉลี่ย 25 นาที
กรณีที่ 2 — กับดัก "ทำไม" ที่ถูกสร้างขึ้นมา นักพัฒนาขอความคิดเห็นจาก AI ถัดจากค่าการหมดเวลา (หมดเวลา = 30) AI เขียนเหตุผลที่สมเหตุสมผล แต่ไม่ถูกต้อง "เพื่อทนต่อเวลาแฝงของเครือข่ายสูง"; เหตุผลที่แท้จริงคือการจำกัดเวลาตามสัญญา 30 วินาทีของบริการดาวน์สตรีม การตีความที่ผิดทำให้นักพัฒนารายต่อมาเพิ่มมูลค่าโดยไม่จำเป็น ซึ่งนำไปสู่เหตุการณ์ที่เกิดขึ้น บทเรียน: เจ้าของรหัสต้องตรวจสอบเหตุผล
กรณีที่ 3 — มาตรฐาน Docstring กลายเป็นแบบอัตโนมัติ โมดูลเสริมที่มี 40 ฟังก์ชันไม่มีเอกสาร AI ได้รับรูปแบบโครงการ (สไตล์ Google) และพารามิเตอร์ที่สร้างขึ้น คำอธิบายการส่งคืนและข้อยกเว้นสำหรับแต่ละฟังก์ชัน นักพัฒนาซอฟต์แวร์ได้ตรวจสอบสิ่งเหล่านี้และแก้ไขการประกาศประเภทที่ไม่ถูกต้องบางประการ การจัดทำเอกสาร 40 ฟังก์ชันลดลงจากประมาณครึ่งวันเหลือเพียงหนึ่งชั่วโมง
เทมเพลตที่คัดลอกได้สี่แบบ
ร่าง README ที่มีโครงสร้าง:
กลุ่มเป้าหมาย: {{เช่น new contributor}} เขียน README แบบร่างตามไฟล์ด้านล่าง ส่วนต่างๆ: วัตถุประสงค์ คุณลักษณะ ข้อกำหนด การติดตั้ง การทำงาน การกำหนดค่า การทดสอบ การมีส่วนสนับสนุน แยกคำสั่งการติดตั้ง/รันออกจากไฟล์จริง ฟิตติ้ง ทำเครื่องหมายสถานที่ที่คุณไม่แน่ใจด้วย "[ยืนยัน]" ที่มา: {{package.json / scripts / example code}}
การอ้างอิง Docstring/API:
เขียน docstring ให้กับฟังก์ชันเหล่านี้ในรูปแบบ {{project style: Google/NumPy/JSDoc}}: สรุปแบบสั้น พารามิเตอร์ (ประเภท + ความหมาย) ส่งคืน ข้อยกเว้นที่ถูกส่งออกไป ตัวอย่างสั้นๆ 1 ตัวอย่าง อย่าทำซ้ำสิ่งที่โค้ด CLEARLY พูด ทำเครื่องหมายการตัดสินใจออกแบบที่กำหนดให้ "ทำไม" เป็น "[ทำไมจำเป็น]" อย่าเขียนเหตุผลที่แต่งขึ้นมา{{code}}
ลบช่องว่างสำหรับความคิดเห็น "ทำไม":
ในโค้ดนี้ นักพัฒนาคนต่อไปอาจถามว่า "ทำไมจึงเป็นเช่นนี้" (ตัวเลขมหัศจรรย์ การตัดสินใจที่ผิดปกติ วิธีแก้ไข) แสดงความคิดเห็น SKELETON สำหรับแต่ละรายการ แต่ปล่อยให้เหตุผลว่างเปล่า ฉันจะกรอกเหตุผล{{code}}
บันทึกการเปลี่ยนแปลง/คำชี้แจงประชาสัมพันธ์:
เขียน {{changelog entry / PR description}} จากส่วนต่างด้านล่าง รูปแบบ: มีอะไรเปลี่ยนแปลง (ในภาษาของผู้ใช้), เพราะเหตุใด (ฉบับ: {{...}}), การเปลี่ยนแปลงที่สำคัญ (ถ้ามี), มีการทดสอบแล้วหรือไม่ ปรับศัพท์เฉพาะทางเทคนิคให้เหมาะกับกลุ่มเป้าหมาย{{diff}}
พรอมต์อ่อน / พรอมต์แข็งแกร่ง
จุดอ่อน: "เขียน README สำหรับโครงการนี้"
แข็งแกร่ง: "กลุ่มเป้าหมาย: นักพัฒนาโคลน repo นี้เป็นครั้งแรก ตามไฟล์แนบ package.json, docker-compose.yml และ scripts/ โฟลเดอร์ ให้เขียน README แบบร่างโดยมีวัตถุประสงค์ ข้อกำหนด การติดตั้ง การดำเนินการ การทดสอบ ส่วนการสนับสนุน แยกคำสั่งจากไฟล์เหล่านี้ อย่าสร้างมันขึ้นมา ทำเครื่องหมายที่ใดก็ได้ที่คุณไม่แน่ใจด้วย [ยืนยัน]"
เวอร์ชันที่แข็งแกร่งจะให้ผู้ชม แหล่งที่มา โครงสร้าง และกฎ "make it, mark it" เพื่อให้เอกสารเป็นไปตามไฟล์จริงและมองเห็นสถานที่ตรวจสอบได้ชัดเจน
ประเภทเอกสาร
เอไอทำได้ดี
มนุษย์เพิ่ม/ยืนยัน
การติดตั้ง README
โครงร่างขั้นตอน
ดำเนินการตามขั้นตอนและยืนยัน
เอกสาร/API
โครงสร้าง พารามิเตอร์ ประเภท
ประเภทที่ถูกต้องและ "ทำไม"
ความคิดเห็นรหัส
สรุป "เขากำลังทำอะไรอยู่"
"เหตุใดจึงเป็นเช่นนั้น" เหตุผล
บันทึกการเปลี่ยนแปลง/ประชาสัมพันธ์
ร่างแรก
ผลกระทบและความแม่นยำ
การตัดสินใจทางสถาปัตยกรรม (ADR)
โครงกระดูก
การตัดสินใจและการประนีประนอมอย่างแท้จริง
เอกสารต้องมีการบำรุงรักษา
ลักษณะที่อันตรายที่สุดของเอกสารคือเมื่อปรากฏว่าเป็นความจริงแม้ว่าจะเป็นเท็จก็ตาม เมื่อรหัสเปลี่ยนแปลงและเอกสารไม่ได้รับการอัพเดต จะทำให้ผู้อ่านเข้าใจผิด AI ทำให้การอัปเดตเป็นเรื่องง่าย: ออกส่วนต่างและถามว่า "การเปลี่ยนแปลงนี้ส่งผลต่อส่วนใดของเอกสาร" คุณอาจถาม แต่เป็นกระบวนการที่ช่วยให้มั่นใจถึงความทันสมัย — ทำให้การอัปเดตเอกสารเป็นส่วนหนึ่งของการเปลี่ยนแปลงโค้ด (เกณฑ์การยอมรับของ PR) AI เร่งความเร็ว ทีมงานสร้างวินัย
ข้อควรระวัง: ห้ามเผยแพร่โดยไม่ตรวจสอบขั้นตอนการติดตั้งใน README เอกสารที่ "น่าจะใช้ได้" อาจทำลายวันแรกของนักพัฒนารายใหม่และกัดกร่อนความไว้วางใจ ดำเนินขั้นตอนต่างๆ ด้วยตนเองในสภาพแวดล้อมที่สะอาด
ข้อผิดพลาดทั่วไป
- รับ "ทำไม" เพื่อให้เหมาะกับ AI การให้เหตุผลที่เป็นเท็จนั้นเลวร้ายยิ่งกว่าการไม่มีเหตุผล เจ้าของโค้ดควรเขียนเหตุผลในการออกแบบ
- ไม่ตรวจสอบขั้นตอนการติดตั้ง README ที่ใช้งานไม่ได้จะทำลายความไว้วางใจ
- ความคิดเห็นที่ไม่จำเป็นซ้ำรหัส มันก่อให้เกิดเสียงรบกวน ซึ่งบดบังการตีความ "ทำไม" ที่แท้จริง
- ไม่ระบุกลุ่มเป้าหมาย เอกสารที่ไม่ชัดเจนว่าใครเขียนถึงใครก็ไม่มีประโยชน์สำหรับมือใหม่หรือผู้เชี่ยวชาญ
- แยกการอัพเดตออกจากกระบวนการ หากเอกสารไม่ได้รับการอัพเดตด้วยโค้ดจะทำให้เข้าใจผิดอย่างรวดเร็ว
โดยสรุป
AI นำภาระทางกลไกไปมากจากเอกสาร: ฉบับร่างด่วน README, เอกสารเอกสาร, การอ้างอิง API, บันทึกการเปลี่ยนแปลง และคำอธิบาย PR แต่ไม่สามารถรู้ได้ว่า "ทำไม" ซึ่งเป็นชั้นที่มีค่าที่สุด และการสร้างมันขึ้นมานั้นเป็นอันตราย การแบ่งส่วนงานมีความชัดเจน: AI สร้าง "อะไร/อย่างไร" โดยเติม "ทำไม" ระบุผู้ชม จัดเตรียมทรัพยากร กำหนดโครงสร้าง ทำเครื่องหมายสถานที่ให้เหมาะสม และตรวจสอบแต่ละขั้นตอนการติดตั้งโดยดำเนินการด้วยตนเอง ทำให้เอกสารเป็นส่วนสำคัญของการเปลี่ยนแปลงรหัส
งานสมัคร
เลือกโมดูลหรือโครงการขนาดเล็กที่มีเอกสารขาดหายไปหรือล้าสมัย ขั้นแรกให้สร้างโครงร่างจาก AI ด้วยเทมเพลต “แบบร่าง README ที่มีโครงสร้าง” (หรือสตริงเอกสาร) อย่าลืมให้แหล่งที่มาและกลุ่มเป้าหมาย จากนั้นผ่านแต่ละจุดที่ AI ทำเครื่องหมายว่า [VERIFY] หรือ [WHY NEEDED]: รันขั้นตอนการตั้งค่าจริง ๆ และกรอกการออกแบบ “ทำไม” ด้วยความรู้ของคุณเอง สังเกตว่าต้องแก้ไขกี่ขั้นตอนและคุณเพิ่ม "ทำไม" กี่ขั้นตอน
รายการตรวจสอบ
- [ ] ในเอกสารประกอบ ฉันแยกแยะระหว่างเลเยอร์ "อะไร/อย่างไร" และ "ทำไม"
- [ ] ฉันไม่ได้ให้ AI มาเป็น "ทำไม" ฉันเติมเอง
- [ ] ฉันแจ้งผู้ชมเป้าหมายและไฟล์ต้นฉบับตามจริง
- [ ] ฉันตรวจสอบคะแนน [VERIFY] ที่ AI ทำเครื่องหมายไว้โดยดำเนินการด้วยตนเอง
- [ ] ฉันกำจัดความคิดเห็นที่ไม่จำเป็นซึ่งใช้โค้ดซ้ำ
- [ ] ฉันกำลังทำการอัปเดตเอกสารเป็นส่วนหนึ่งของการเปลี่ยนแปลงโค้ด