วิธีจัดทำเอกสารโครงการที่พัฒนาไปแล้ว

ฉันต้องการทราบว่ามีตัวเลือกใดบ้างสำหรับการจัดทำเอกสารโครงการที่ได้รับการพัฒนาแล้วเนื่องจากผู้พัฒนาที่ทำงานบนไม่ได้เขียนเอกสารแม้แต่หน้าเดียว

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

โครงการได้รับการพัฒนาด้วย PHP และ MySQL ฟังก์ชั่นนั้นมีความคิดเห็นไม่ดีดังนั้นฉันจึงไม่สามารถรับผลลัพธ์ที่ดีได้เมื่อฉันเรียกใช้ด้วย doxygen

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

โดยทั่วไปให้ทำเอกสารมากที่สุดเท่าที่จำเป็นและไม่ต้องเพิ่มเติม องค์กรจำนวนมากต้องการเอกสารเพราะมีคนยืนยันว่าเป็นแนวปฏิบัติที่ดีที่สุด แต่เอกสารท้ายที่สุดรวบรวมฝุ่น

สมมติว่าคนจะใช้เอกสารจริงอย่าพยายามจับภาพรหัสและฐานข้อมูลในระดับที่เล็กที่สุด นักพัฒนาจะดูรหัสสำหรับ minutiae ให้เน้นที่รายละเอียดที่ไม่ปรากฏในรหัสแทนเช่น:

1. กรณีการใช้ผลิตภัณฑ์ที่เป็นไปตาม สิ่งนี้อาจเป็นเรื่องยากเมื่อพิจารณาอายุของผลิตภัณฑ์ แต่การตรวจสอบว่าผลิตภัณฑ์หมายถึงอะไรให้บริบทที่สำคัญแก่ผู้อ่านและผู้ทดสอบที่ไม่ใช่ด้านเทคนิค ใครคือคู่แข่งในตลาด (ถ้ามี) มีอะไรที่แยกออกจากขอบเขตของผลิตภัณฑ์หรือไม่
2. ใด ๆ ที่ชัดเจนความต้องการที่ไม่ใช่หน้าที่ ตัวอย่างเช่นผลิตภัณฑ์ถูกเขียนขึ้นเพื่อรองรับปริมาณที่แน่นอนหรือไม่? ข้อมูลมีอายุเท่าไหร่ แคชใช้ที่ไหน ผู้ใช้จะรับรองความถูกต้องได้อย่างไร การควบคุมการเข้าถึงทำงานอย่างไร
3. บริบทแผนภาพแสดงการทำงานร่วมกันกับระบบอื่น ๆ เช่นฐานข้อมูลแหล่งที่มาของการตรวจสอบการสำรองข้อมูล, การตรวจสอบและอื่น ๆ
4. (ถ้าทราบ) ความเสี่ยงและวิธีการที่พวกเขาถูกลดลงพร้อมกับการลงทะเบียนการตัดสินใจ นี่อาจเป็นเรื่องยากในการหวนกลับ แต่มักจะมีการตัดสินใจที่สำคัญที่มีผลต่อการออกแบบ จับสิ่งที่คุณรู้
5. ทั่วไปรูปแบบการออกแบบหรือแนวทางการออกแบบ ตัวอย่างเช่นมีวิธีมาตรฐานในการเข้าถึงฐานข้อมูลหรือไม่ มีมาตรฐานการเข้ารหัสหรือการตั้งชื่อหรือไม่?
6. พา ธ โค้ดที่สำคัญมักใช้โฟลว์ชาร์ตหรือกิจกรรม UML หรือไดอะแกรมลำดับ อาจไม่มีสิ่งใดในโครงการ แต่โดยทั่วไปผู้ใช้ทางธุรกิจมักจะพูดชัดแจ้ง

แม้ว่าข้อมูลทั้งหมดนี้ไม่สามารถใช้ได้เริ่มต้นตอนนี้ นักพัฒนาที่มาหลังจากคุณจะขอบคุณ

การทดสอบหน่วยอัตโนมัติที่ดีหรือกรณีทดสอบอาจเป็นเอกสารที่มีประโยชน์แม้ว่าจะยากสำหรับผู้ที่มีความรู้ด้านเทคนิค

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

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

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

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

สิ่งแรกสิ่งแรกใครคือกลุ่มเป้าหมายของคุณ นักพัฒนาในอนาคตหรือนักธุรกิจคนอื่น ๆ ? ด้วยคำตอบของคำถามนั้นในใจ:

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

การประมวลผลหรือตรรกะที่ซับซ้อนฉันจะใช้ state state, data flow diagram หรือ sequence diagram ทำไดอะแกรมเอนทิตีอย่างแน่นอนจากนั้นออกแบบ DB schema (สองสิ่งที่ต่างกัน!) อาจเป็นไดอะแกรมคลาสพื้นฐาน แต่ทำให้เรียบง่ายเพียงสังเกตสิ่งสำคัญที่น่าสนใจ devs สามารถเข้าใจสิ่งนั้นได้โดยดูที่โค้ด

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

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

คำถามคือคุณต้องการจัดทำเอกสารตามที่เป็นอยู่ในปัจจุบันหรือตามที่ควรจะเป็นหรือไม่?

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

ฉันเกรงว่าถ้าคุณเอกสารตอนนี้คุณจะจบลงด้วยการทิ้งงานส่วนใหญ่ของคุณเมื่อรหัสถูก refactored

ฉันจะใช้วิธีการดังต่อไปนี้:

• ทำเอกสารที่ไม่จำเป็นให้มากที่สุดโดยปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุด เลือกชื่อคลาสที่ดีชื่อเมธอดชื่อตัวแปรที่คุณสามารถเข้าใจได้โดยสัญชาตญาณ
• ทำลายชั้นเรียนมอนสเตอร์ขนาดใหญ่และ / หรือฟังก์ชั่นที่เหมาะสม
• ใช้ความคิดเห็น PHPdoc - คุณสามารถใช้เครื่องมือเพื่อสร้างเอกสาร API
• เขียนการทดสอบสำหรับมัน: การทดสอบจะช่วยให้คุณเข้าใจหรือกำหนดรหัสที่ควรทำ

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