เอกสารการออกแบบควรมีการอภิปรายถึงข้อดี / ข้อเสียของการออกแบบที่กำหนดหรือควรมุ่งเน้นไปที่ข้อเท็จจริงและเหตุผล?

ขณะนี้ฉันกำลังปรับปรุงเอกสารการออกแบบเพื่อให้ถูกต้องและทันสมัยสำหรับนักพัฒนาในอนาคต

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

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

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

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

คำถาม:

• เอกสารการออกแบบควรยึดติดกับข้อเท็จจริงดิบ ("นี่คือการออกแบบ") และเหตุผล ("นี่คือเหตุผลที่นี่คือการออกแบบ") หรือควรใช้เพื่อชี้ให้เห็นปัญหาที่ไม่บกพร่องด้วยการออกแบบที่อาจเป็นปัญหาสำหรับ นักพัฒนาในอนาคต?
• หากไม่ควรใช้เอกสารการออกแบบเพื่อบันทึกข้อมูลนี้ควรใช้เอกสารประเภทใดและควรมีการอภิปรายเกี่ยวกับเหตุผลในการออกแบบการแลกเปลี่ยนและปัญหาที่ทราบ (ซึ่งไม่ใช่ข้อบกพร่องเนื่องจากมีการติดตามข้อบกพร่อง) ใช้เครื่องมืออื่น ๆ )?

หากสามารถสรุปข้อดีข้อเสียในประโยคหนึ่งหรือสองประโยคได้ก็จะถือว่าเป็นการออกแบบเอกสาร สิ่งใดอีกต่อไปควรแยกออก

ที่ฉันทำงานอยู่ในขณะนี้มักจะมีเอกสาร "แยกการออกแบบ" เพื่อติดตามการตัดสินใจที่สำคัญและใหญ่ทั้งหมด มักจัดรูปแบบด้วยย่อหน้าที่อธิบายถึงปัญหา (เช่น "ไฟล์บางไฟล์จำเป็นต้องย้ายจากเซิร์ฟเวอร์ไปยังผู้ใช้บางคนในตอนท้ายของแต่ละรอบการประมวลผลมีหลายวิธีในการทำเช่นนี้ ... ") ตารางที่มีคอลัมน์ " คำอธิบายโซลูชัน "(เช่น" ย้ายไฟล์ผ่าน FTP ")," ข้อดี "(เช่น" ง่ายสำหรับผู้ใช้ในการจัดการ ")," ข้อเสีย "(เช่น" ไม่ปลอดภัยเพียงพอสำหรับการปฏิบัติตาม ABC-XYZ ") และบทสรุปที่ อธิบายว่าเหตุใดจึงเลือกการตัดสินใจเฉพาะ (เช่น "FTP จะไม่ถูกใช้เพราะจะไม่สามารถทำตามข้อกำหนดบางประการ") เอกสารการออกแบบมักจะอ้างอิงการตัดสินใจที่เลือกเท่านั้น

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

ไม่ใช่ "อย่างใดอย่างหนึ่งหรือ"

ไม่มีใครอ่านเอกสารตั้งแต่แรก พวกเขาอ่านอย่างดีที่สุด ดังนั้นเขียนเอกสารให้น้อยที่สุด เอกสารเดียวคือทุกคนมีความอดทน เอกสาร "ไม่ใช่ desgin" ที่สองที่มี "ปัญหาอื่น ๆ " ไม่น่าจะอ่านได้เลย

ข้อดีของเอกสารเดียว? ผู้คนอาจอ่านมัน

ข้อเสียของเอกสารเดียว? น้อย ส่วนใหญ่จะล้าสมัย

ข้อดีของเอกสารหลาย ๆ ไม่มี.

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

หลีกเลี่ยงการบิดมือ

เอกสารข้อดีข้อเสียสามารถลากเข้าไปในส่วนลึกไม่ จำกัด ของการสนทนาที่สร้างความรำคาญใจและอะไร

หากคุณรู้สึกว่าจำเป็นต้องนำเสนอข้อดีข้อเสียให้สั้นและตรงประเด็น

มุ่งเน้นไปที่สิ่งที่เป็น

เก็บสิ่งที่ไม่ลงไปที่กระดูกเปลือย

หากคุณได้ทำการศึกษาเปรียบเทียบหรือสำรวจทางเลือกจริง ๆ แล้วให้จัดทำเอกสารที่ แต่หากคุณกำลังพิจารณาทางเลือกอื่น ๆ ให้ย่อเล็กสุด

นี่ไม่ควรเป็นประวัติส่วนตัวของคุณเกี่ยวกับการทดลองและความยากลำบาก

• มีปัญหาหรือไม่? ซ่อมมัน? ใช้เวลาหลายสัปดาห์ ดิ้นรนจริงๆเหรอ? เรื่องราวเล็ก ๆ น้อย ๆ ที่น่าสนใจ มันได้รับการแก้ไขในรหัส รุ่นก่อนหน้ารุ่นผิดรุ่น buggy และรุ่นประสิทธิภาพต่ำนั้นไม่สำคัญ พวกเขาเป็นบล็อกอาหารสัตว์ที่ดีที่สุด

• ยังมีปัญหาอยู่เหรอ? ไม่ได้รับการแก้ไข? นั่นหมายถึงมีทางเลือกอื่น เอกสารนี้

ข้อเท็จจริงสำคัญ 3 ประการในกระบวนการตัดสินใจ:

• สิ่งที่พยายามและไม่ทำงาน (และทำไมมันไม่ทำงานเพราะคุณกำหนดเป้าหมายเป้าหมายที่เคลื่อนที่)
• คืออะไร
• สิ่งที่อาจเป็น (รอให้ X ติดตั้ง ... )

อย่างไรก็ตามนอกเหนือจาก "สิ่งที่เป็น" คนอื่น ๆ ทั้งหมดจะสร้างความสับสนให้ผู้อ่านและป้องกันไม่ให้เธอคลานระบบ

ฉันชอบความคิดของการจับภาพอีก 2 แม้ว่าพวกเขาจะน่าสนใจน้อยกว่าสำหรับการเรียนรู้ระบบพวกเขาสามารถประหยัดเวลาเมื่อเปลี่ยนมัน

ดังนั้นฉันจะสร้างความคิดที่เปิดเผย @FrustratedWithFormsDesigner ด้วยการบิด แทนที่จะสร้างเอกสารอื่นด้วยวัฏจักรชีวิตของมันเองฉันจะยึดส่วนภาคผนวกไว้ จากนั้นสำหรับการตัดสินใจแต่ละครั้งที่ควรค่าแก่การอภิปรายฉันจะชี้ไปที่รายการที่เกี่ยวข้องในภาคผนวก

ใช่. เอกสารการออกแบบควรอธิบายถึงประโยชน์ความเสี่ยงและสมมติฐานที่เกี่ยวข้องกับการออกแบบที่อธิบายไว้ เอกสารการออกแบบมีวัตถุประสงค์หลายประการ:

1. รับการออกแบบที่จดบันทึกไว้เพื่อให้ทุกคนเข้าใจและเพื่อความเข้าใจของแต่ละคนจะไม่เปลี่ยนแปลงไปตามกาลเวลา

2. สื่อสารการออกแบบให้กับบุคคลที่ไม่ได้ทำงานด้านเทคนิคในโครงการ

3. ช่วยในการจัดตารางเวลาการจัดสรรทรัพยากรการประมาณราคาและการวางแผนอื่น ๆ

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

5. มักจะเป็นหนึ่งในสิ่งที่ต้องส่งมอบตามสัญญา

(อาจมีคนอื่น ๆ แต่สิ่งเหล่านี้เป็นการเริ่มต้นที่ดี)

หนึ่งในวัตถุประสงค์เหล่านี้ได้รับการบริการอย่างดีจากเอกสารการออกแบบที่อธิบายอย่างชัดเจนว่าเหตุใดจึงเลือกการออกแบบนี้และความเสี่ยงที่เกี่ยวข้องคืออะไร:

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

2. สำหรับสมาชิกในทีมที่ไม่ใช่ด้านเทคนิคการทำความเข้าใจความเสี่ยงและผลประโยชน์มักจะสำคัญกว่ารายละเอียดของการออกแบบ

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

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

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

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

นี่คือรายการบล็อกของการเขียนเอกสารการออกแบบที่คุณอาจพบว่ามีประโยชน์

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

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

โดยส่วนตัวฉันจะไม่ใส่ไว้ในเอกสารการออกแบบ เอกสารการออกแบบควรสรุปว่ามันเป็นอย่างไรไม่ใช่สาเหตุ

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

ฉันเห็นด้วยกับคุณเกี่ยวกับการใส่เหตุผลลงในเอกสารการออกแบบ

อย่างไรก็ตาม,

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

ดังนั้น,

ฉันจะใส่เหตุผลเพียงเกี่ยวกับการเปลี่ยนแปลงที่เกิดขึ้นในการออกแบบในระหว่างการบำรุงรักษา