เหตุใดการเขียนเอกสารการออกแบบซอฟต์แวร์จึงสำคัญ

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

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

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

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

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

เหตุใดเอกสารการออกแบบซอฟต์แวร์จึงมีความสำคัญ

ดังนั้น เมื่อคุณทำโครงการใหม่ ก่อนที่คุณจะเปิด Xcode หรือ Visual Studio คุณต้องมีเป้าหมายการออกแบบที่ชัดเจนและตกลงร่วม กัน และควรกำหนดเป้าหมายเหล่านี้ในเอกสารข้อกำหนด หากไคลเอนต์ไม่ได้เขียน คุณควรเขียน และส่งให้พวกเขาเพื่อตรวจสอบก่อนที่คุณจะเปิด IDE ของคุณด้วยซ้ำ และ ถ้าคุณพบลูกค้าที่พูดว่า "เราไม่มีเวลาสำหรับเอกสารการออกแบบ" ตรงไปตรงมา คุณควรเดินออกจากโครงการ เพราะมีปัญหาอยู่ข้างหน้า ข้อกำหนดไม่จำเป็นต้องยาวเป็นพิเศษ อาจเป็นเพียงไม่กี่หน้า แต่อย่างน้อยที่สุดก็ควรจัดวางส่วนต่อประสานกับผู้ใช้ รวมไวร์เฟรม (หากมีองค์ประกอบ UI) และกำหนดเหตุการณ์สำคัญที่เสร็จสิ้น

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

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

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

ข้อกำหนดการออกแบบซอฟต์แวร์ควรระบุอะไรจริง ๆ ?

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

หน้าจอผู้ใช้

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

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

1. การควบคุมมองเห็นได้เสมอและ/หรือเปิดใช้งานหรือไม่ รัฐของพวกเขาเปลี่ยนแปลงภายใต้เงื่อนไขใด?
2. ดูเหมือนบิตแมป—เป็นปุ่มหรือไม่
3. การเปลี่ยนแปลงใดเกิดขึ้นระหว่างสถานะและมุมมองเหล่านี้ และพวกเขาควรจะเคลื่อนไหวอย่างไร?

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

ขนาดหน้าจอก็มีความสำคัญเช่นกัน มี (ในขณะที่เขียน) หน้าจอ iPhone สามขนาด โครงลวดแยกสำหรับหน้าจอ 3.5” และ 4” อาจมากเกินไป แต่คุณอาจต้องสร้างมันขึ้นมา ในกรณีส่วนใหญ่ คุณสามารถเปลี่ยนสัดส่วนได้ง่ายๆ

หากลูกค้าของคุณจัดหากราฟิกให้กับคุณ ตรวจสอบให้แน่ใจว่ามีขนาดถูกต้องด้วยอัตราส่วนกว้างยาวที่เหมาะสม การเปลี่ยนบิตแมปที่มีข้อความหรือวัตถุ (เช่น วงกลม) จะทำให้เกิดการบิดเบือน หากไม่ตรงกัน แจ้งให้ลูกค้าสร้างใหม่ด้วยขนาดที่ตรงกัน อย่าคิดเอาเองว่าคุณสามารถขยายหน้าจอขนาด 3.5” เป็น splash ขนาด 4” แล้วหมุนไปพร้อมกับมัน

ฟังก์ชั่น

คำถามสำคัญที่ต้องถามในเอกสารการออกแบบแอปพลิเคชัน:

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

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

เหตุการณ์สำคัญ

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

ตัวอย่างข้อมูลจำเพาะการออกแบบซอฟต์แวร์

ที่นี่ ฉันจะจัดวางโครงสร้างตัวอย่างเอกสารการออกแบบที่เหมาะสม แน่นอนว่าควรปรับเปลี่ยนเทมเพลตนี้ตามต้องการ สำหรับตัวอย่างอื่น ดูข้อมูลจำเพาะตัวอย่างของ Joel Spolsky ตามบทความนี้ เขาเข้าใกล้เอกสารแตกต่างกันเล็กน้อย แต่มีความรู้สึกคล้ายกัน

คำแถลงเป้าหมาย

รวมย่อหน้าสั้น ๆ ที่อธิบายโครงการและกลุ่มเป้าหมาย

รายละเอียดการทำงาน

แอปพลิเคชั่น ทำ อะไร ? สถานะของแอปพลิเคชันใด (คำอธิบายระดับสูงของสถานการณ์ผู้ใช้หลัก) ที่ผู้ใช้จะพบเจอ

ตัวอย่างเช่น คำอธิบายฟังก์ชันของคุณอาจมีลักษณะดังนี้:

• วิ่งครั้งแรก
• การสร้าง _____ ใหม่ (เกม การค้นหา ฯลฯ)
• ปฏิบัติการ
• ความเป็นมาและพฤติกรรมเบื้องหน้า

หน้าจอผู้ใช้

รวมโครงร่างสำหรับแต่ละหน้า พร้อมคำอธิบายโดยละเอียดของ:

• การควบคุมแต่ละรายการ รวมถึงสถานะ (เปิดใช้งาน/ปิดใช้งาน/เน้น) และการดำเนินการ
• รองรับการวางแนวและการเปลี่ยนภาพระหว่างกัน
• ฟังก์ชั่นที่แสดง
• การจัดการข้อผิดพลาด
• ขนาดและข้อจำกัด

นี่คือโครงร่างที่เกี่ยวข้องกับแอพ iOS ล่าสุดของฉัน NotifEye:

หากคุณสนใจ ฉันได้สร้างแบบจำลองเหล่านี้โดยใช้เครื่องมือสร้างเฟรมเรตของ Balsamiq

ตัวอย่างเช่น คำอธิบาย UI ของคุณอาจมีลักษณะดังนี้:

• แถบนำทาง
  • ปุ่มควบคุมการนำทางด้านซ้าย: กลับสู่หน้าแรก
  • แถบชื่อเรื่อง: หน้าจอปัจจุบันหรือชื่อการทำงาน
  • ปุ่มใหม่: สร้างสิ่งใหม่
• มุมมองตาราง
  • ส่วนที่ 0: ชื่อส่วน
  • ส่วนที่ 0 แถว:
    • การควบคุมแถว 0 (เช่น รูปภาพ)
    • ข้อความบรรทัด0
    • ข้อความบรรทัด2

เหตุการณ์สำคัญ

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

ตัวอย่างเช่น ส่วนเหตุการณ์สำคัญในเทมเพลตเอกสารการออกแบบของคุณอาจมีลักษณะดังนี้:

1. Facade Application แสดงหน้าจอและการเปลี่ยนชั่วคราวและภาพตัวอย่าง/ข้อความ
2. Communication Protocol: แอปพลิเคชันเชื่อมต่อกับเครือข่าย/เซิร์ฟเวอร์
3. เป้าหมายการทำงาน 1: …
4. แอปพลิเคชันอัลฟ่า (พร้อมฟังก์ชันเต็มรูปแบบ)
5. ความเสถียร
6. ปล่อย

ตรวจสอบให้แน่ใจว่าเอกสารประกอบซอฟต์แวร์ยังคงมีความเกี่ยวข้อง

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

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

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

1. นักพัฒนาเพิ่งทำงานอะไร
2. นักพัฒนาซอฟต์แวร์กำลังทำงานเกี่ยวกับอะไรอยู่?
3. นักพัฒนาจะทำอะไรต่อไป?