เหตุใดห้องสมุดจำนวนมากจึงไม่มีเอกสารไม่ดี [ปิด]

ในทำนองเดียวกันโครงการโอเพ่นซอร์สจะประสบความสำเร็จได้อย่างไรหากไม่มีเอกสารเกี่ยวกับการออกแบบหรือสถาปัตยกรรม? คำถามฉันอยากรู้อยากเห็น: ทำไมห้องสมุดจำนวนมากจึงขาดเอกสารคู่มือผู้ใช้?

มุมมองของฉันคือ:

1. ทุกคนส่วนใหญ่ยอมรับว่าการอ่านซอร์สโค้ดนั้นยากกว่าการเขียนซอร์สโค้ด
2. หากไม่มีเอกสารเราจะต้องอ่านซอร์สโค้ดของไลบรารีเพื่อใช้ไลบรารีนั้น
3. ดังนั้นการใช้ไลบรารี่ที่ไม่มีเอกสารจะทำงานได้ดีกว่าการสร้างไลบรารี่ขึ้นใหม่จากศูนย์
4. ด้วยเหตุนี้หากคุณต้องการให้คนอื่นใช้ห้องสมุดของคุณคุณควรจะมีเอกสารที่ดีกว่า

ฉันรู้ว่านักพัฒนาจำนวนมากไม่ชอบเขียนเอกสารและฉันยอมรับว่ามันอาจเป็นงานที่น่าเบื่อ แต่มันเป็นงานที่สำคัญ ฉันยังบอกด้วยว่ามันสำคัญกว่าที่ห้องสมุดมีเอกสารที่ดีกว่ามีส่วนต่อประสานโปรแกรมเมอร์ที่ดีที่สุดในโลก (ผู้คนใช้ไลบรารีที่ไม่เหมาะสมอยู่ตลอดเวลามีผู้ใช้เพียงไม่กี่คนที่ไม่มีเอกสาร)

โอ้โปรดทราบว่าเมื่อฉันพูดเอกสารฉันหมายถึงเอกสารจริง ไม่ใช่ Sandcastle / Javadoc / Doxygen boilerplate

ฉันคิดว่าคุณตอบคำถามของคุณเองเป็นส่วนใหญ่: เพราะโดยส่วนใหญ่แล้วนักพัฒนาซอฟต์แวร์จะไม่รำคาญ ปัญหานี้เป็นที่แพร่หลายโดยเฉพาะในโครงการอาสาสมัคร

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

ในกรณีทั่วไปสิ่งที่เขียนมีภาพรวมระดับสูงมาก ("นี่คือไลบรารีสำหรับทำสิ่งที่ยอดเยี่ยม!") จากนั้นคำอธิบายระดับต่ำมาก (ประเภทและคำอธิบายของแต่ละพารามิเตอร์ที่จะส่งผ่านไปยังแต่ละฟังก์ชัน) น่าเสียดายที่ไม่ค่อยมีระดับกลางเกี่ยวกับทฤษฎีทั่วไปว่าสิ่งต่าง ๆ ควรทำงานอย่างไรชิ้นส่วนเข้าด้วยกัน ฯลฯ สิ่งเหล่านี้กลับไปสู่ความจริงที่ว่านักพัฒนามักไม่ได้พยายามจัดรูปแบบหาเหตุผลเข้าข้างตนเองหรือเข้าใจ รหัสในระดับของรายละเอียดนั้น อย่างน้อยในบางกรณีที่ฉันเคยเห็นนักพัฒนาที่ถูกขอให้เขียนเอกสารในระดับนั้นพบว่ามันค่อนข้างมีปัญหา - จนถึงจุดที่หลายคนต้องการเขียนรหัสใหม่ดังนั้นมันจะจัดระเบียบง่ายขึ้นและอธิบายได้ง่ายกว่าในระดับนั้น รายละเอียด

การเขียนในระดับที่ดีของนามธรรมนั้นมักจะยาก - และหากนักพัฒนาไม่ได้คิดเกี่ยวกับมันในระดับที่เป็นนามธรรมพวกเขามักจะพบรหัสที่ค่อนข้างน่าอายและอาจต้องการเขียนใหม่ก่อนที่พวกเขาจะมีความสุข เกี่ยวกับการปล่อยมันทั้งหมด

ฉันคิดว่าบางครั้งมันเป็นเพราะนักพัฒนาซอฟต์แวร์ห่อหุ้มโค้ดที่มัน "ชัดเจน" กับเขา / เธอถึงวิธีการทำงานและพวกเขาไม่สามารถเห็นได้ว่าทำไมคนอื่นถึงมองไม่เห็น ในทำนองเดียวกันเว็บไซต์ของผลิตภัณฑ์จำนวนมากบอกว่าผลิตภัณฑ์ของตนนั้นวิเศษเพียงใด แต่อย่าบอกคุณว่ามันทำอะไรได้จริง!

คุณชี้คำตอบด้วยตัวคุณเอง:

ฉันรู้ว่านักพัฒนาจำนวนมากไม่ชอบเขียนเอกสารและฉันยอมรับว่ามันอาจเป็นงานที่น่าเบื่อ

ในฐานะโปรแกรมเมอร์เราสนุกกับการเขียนโค้ด แต่น้อยคนนักที่จะสนุกกับการเขียนเอกสาร

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

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

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

ในความคิดของฉันความสามารถในการเขียนเอกสารที่ดีมันเป็นหนึ่งในลักษณะสำคัญที่แตกต่างโปรแกรมเมอร์ที่ดีจากโปรแกรมเมอร์ปานกลาง

บุคคลที่มีคุณสมบัติที่ดีที่สุดในการเขียนเอกสารก็เป็นบุคคลที่มีแรงจูงใจน้อยที่สุดในการทำเช่นนั้น:

เขา (หรือเธอ) คือ:

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

ฉันไม่สามารถคิดถึงใครได้เลยที่มีโอกาสน้อยที่จะไป "อืมฉันควรใช้เวลาสองสามชั่วโมงเขียนเอกสารที่เหมาะสมสำหรับเรื่องนี้" ทำไมเขาจะ?

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

ดังนั้นแม้ในกรณีที่หายากซึ่งนักพัฒนาซอฟต์แวร์เต็มใจที่จะเขียนเอกสารจริงมันเป็นโอกาส 50/50 ที่นักพัฒนาได้รับการล้างสมองโดยลัทธินี้ในการคิดว่าสิ่งที่จำเป็นต้องมีคือการกรอกความคิดเห็นเช่นบอกคุณว่าคุณชอบ ที่ "ฟังก์ชันFoo getFoo()ส่งคืนวัตถุประเภท Foo และใช้เพื่อรับวัตถุ Foo"

เอกสาร? เราไม่ต้องการเอกสารที่ไม่มีกลิ่นเหม็น!

ฉันรู้ว่ารหัสทำงานอย่างไรดังนั้นทำไมฉันถึงต้องใช้เวลาในการบันทึกรหัสของฉัน นอกจากนั้นฉันต้องทำโปรเจคนี้ในวันศุกร์และฉันจะทำไม่ได้เพราะมันเป็น ...