วิธีวาดไดอะแกรมสถาปัตยกรรมซอฟต์แวร์ (2022)

 (terrastruct.com)
3 คะแนน โดย GN⁺ 2023-10-28 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • ไดอะแกรมสถาปัตยกรรมที่ดีช่วยให้การสื่อสารไอเดียและการทำงานร่วมกันคงอยู่ได้นาน ไม่ใช่ด้วยการตกแต่ง แต่ด้วย ระดับของการนามธรรมที่เหมาะสม, ความเป็นปัจจุบัน และการขจัดความกำกวม
  • พื้นฐานคือ การลดระยะห่างระหว่างเพื่อนบ้านให้ต่ำที่สุด โดยวางองค์ประกอบที่เชื่อมต่อกันไว้ใกล้กัน และยิ่งไดอะแกรมมีขนาดใหญ่ ก็ยิ่งต้องลบและวาดใหม่ซ้ำไปมา
  • ความสมมาตร ไม่ได้แค่สร้างความประทับใจที่ดูดี แต่ยังช่วยเสริมการสื่อความหมาย เช่น การวางอินพุตไว้คนละด้านกับเอาต์พุต
  • หากรักษา การจัดกึ่งกลางของรูปทรง ไว้ได้ แม้แนวคิดที่ซับซ้อนก็ดูซับซ้อนน้อยลง และเมื่อเพิ่มองค์ประกอบใหม่ การจัดวางโดยรวมก็จะไม่เสียทรง
  • กลุ่มคอนเทนเนอร์ ที่มีป้ายกำกับช่วยให้เห็นได้ในพริบตาเดียวถึงการแยกสภาพแวดล้อมอย่าง AWS และ Azure, การนามธรรมอย่าง implementation ของ ReaderWriter, และการจัดกลุ่มออบเจ็กต์ที่เกี่ยวข้องกันอย่าง Cores

เงื่อนไขของไดอะแกรมที่ใช้งานได้ยาวนาน

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

หลักการสร้างเลย์เอาต์ที่อ่านง่าย

  • การลดระยะห่างระหว่างเพื่อนบ้านให้ต่ำที่สุด

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

  • การมองหาความสมมาตร

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

  • การจัดกึ่งกลาง

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

  • การใช้กลุ่มคอนเทนเนอร์

    • การแบ่งไดอะแกรมออกเป็นหลายพื้นที่พร้อมป้ายกำกับ ช่วยให้ผู้อ่านเข้าใจโครงสร้างได้ง่ายขึ้น
    • คอนเทนเนอร์สามารถเพิ่มข้อมูลต่อไปนี้ให้กับไดอะแกรมได้
      • เพิ่ม บริบท เช่น “บริการเหล่านี้อยู่บน AWS และบริการเหล่านี้อยู่บน Azure”
      • แสดง การนามธรรม เช่น “ทั้งหมดนี้คือ implementation ของ ReaderWriter”
      • จัดกลุ่มออบเจ็กต์ที่เกี่ยวข้องกัน เช่น การรวม core 1, 2, 3, 4 ไว้ในคอนเทนเนอร์ “Cores”

หัวข้อที่จะต่อในตอนถัดไป

  • Part 2 จะพูดต่อในหัวข้อต่อไปนี้
    • การวาดเส้นทางของ edge
    • ขนาดและตำแหน่งของป้ายกำกับ
    • สี
    • ไอคอน

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2023-10-28
ความคิดเห็นจาก Hacker News

  • ผมชอบใช้ D2 ทำไดอะแกรมอยู่ คล้ายกับ mermaid.js แต่มีตัวเลือกการจัดรูปแบบมากกว่า และโดยส่วนตัวคิดว่าไวยากรณ์ก็ดีกว่า
    เคยเขียนบทความสั้น ๆ เกี่ยวกับเรื่องนี้ไว้ด้วย: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • รู้สึกว่าไดอะแกรมไม่ควรสวยเกินไป เช่น สีควรถูกใช้เพื่อ สื่อความหมาย ไม่ใช่เป็นการเลือกเชิงสุนทรียะหรือศิลปะ
      เข้าใจว่าไดอะแกรมซอฟต์แวร์ที่หน้าตาไม่สวยอาจดูไม่เพลิน แต่การตกแต่งก็คล้ายกับการใส่เส้นโค้งลงในกราฟเส้น ถึงจะดูดีขึ้นทางสายตา แต่ไปรบกวนข้อมูลที่ต้องการสื่อ
    • ลองทำตามตัวอย่างแล้ว เจ๋งมากจริง ๆ แต่ต่างจากคำแนะนำ มันเรนเดอร์จากบนลงล่าง ไม่ใช่ ซ้ายไปขวา
      เรนเดอร์ตัวอย่างแรก x -> y เป็น SVG แล้วเปิดเฉพาะ SVG ในเบราว์เซอร์ และลองค้นหาทั้งเอกสารว่าจะจัดแนวเอาต์พุตอย่างไร แต่หาไม่เจอ
      เพราะเอกสารแนะนำกับผลลัพธ์จริงไม่ตรงกัน เลยเลิกใช้ ค้นด้วย "d2lang connection left to right" แล้วไปถึง https://d2lang.com/tour/layouts/ ซึ่งดูเหมือนไม่ได้ลิงก์จากเอกสารภาพรวม ถ้าเพิ่มไว้ก็น่าจะช่วยผู้เข้าชมได้
    • https://flowchart.fun/ ช่วยวาด โฟลว์ชาร์ต เพื่อทำความเข้าใจกระบวนการของระบบได้อย่างรวดเร็วมาก จุดที่ชอบที่สุดคือใช้งานได้เป็นธรรมชาติและวนปรับแก้ได้เร็ว ส่วน CSS แบบกำหนดเองสำหรับจัดสไตล์ก็ค่อนข้างมีประโยชน์
      ถ้าจำกัดเฉพาะโฟลว์ชาร์ต ผมมองว่าเป็นหนึ่งในเครื่องมือไดอะแกรมแบบข้อความที่ง่ายและเร็วที่สุดเท่าที่เคยใช้มา
    • D2 มี เอนจินเลย์เอาต์ tala ที่ดีมาก แต่ถ้าจะใช้ต้องมีไลเซนส์แบบเสียเงิน ส่วนเอนจินอีกสองตัวที่เหลือไม่ได้ดีเท่านั้น
    • ผมชอบและใช้ mermaid บ่อย แต่คงต้องไปดู D2 ด้วย ผมมองว่า ไดอะแกรมแบบประกาศ เป็นเครื่องมือที่ทรงพลังในการจับความคิดให้อยู่ในรูปแบบที่อ่านง่าย และทำให้จัดการเวอร์ชันได้เหมือนข้อความอื่น ๆ

  • เมื่อระบบเริ่มเปลี่ยน ไดอะแกรมสวย ๆ จะดูแลรักษายากมาก ลองนึกภาพว่าต้องเพิ่มกล่องใหม่กลางไดอะแกรมที่ซับซ้อนอยู่แล้ว อาจต้องใช้เวลาหนึ่งชั่วโมงเพื่อจัดทุกอย่างใหม่
    เวลาของนักพัฒนาในยุค 2020s น่าจะเอาไปใช้กับการจัดการไดอะแกรมแบบโค้ดดีกว่า: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • ผมมักพูดเล่นเสมอว่า 10% ของการทำไดอะแกรมคือการสร้างไดอะแกรมจริง ๆ ส่วนอีก 90% คือ การจัดแนวลูกศร
      แต่เอาเข้าจริงเหมือนจะไม่ใช่มุกแล้ว
    • เคยดูแล โมเดล C4 เพื่อนำเข้าไปแสดงใน structurizr.com พูดตรง ๆ ว่าไม่สนุกเลย โค้ดอย่างเดียวไม่ได้ให้ความเข้าใจเชิงสัญชาตญาณและภาพรวมแบบที่ได้จากไดอะแกรม และไม่มีพรีวิวในเครื่องแบบรวดเร็ว ต้องอัปโหลดโค้ดขึ้นเซิร์ฟเวอร์
      ที่แย่กว่านั้นคือพอเพิ่มกล่องใหม่ โดยปกติต้องจัดลูกศรใหม่ทั้งหมด ผลคือไดอะแกรมไม่สามารถคงสภาพอัปเดตล่าสุดได้อย่างต่อเนื่อง
      สำหรับ sequence diagram ตอนใช้ plantML ดีกว่า งานเองทำง่ายกว่า ผลลัพธ์จากอินเทอร์พรีเตอร์โดยทั่วไปก็ใช้งานได้โดยแทบไม่ต้องปรับเอง
    • ในบทความก็พูดถึงว่าการแก้ไดอะแกรมใช้เวลามาก ซึ่งในความเป็นจริงก็เป็นแบบนั้นจริง ๆ และคงดีถ้าสามารถทำตามสคีมามาตรฐานได้อย่างถูกต้อง และเครื่องมือมีตัวเลือก จัดรูปแบบอัตโนมัติ
    • พอขยับองค์ประกอบและจัดใหม่ ก็ต้องเรียนรู้ไดอะแกรมทั้งอันใหม่อีกครั้ง ถ้า frobnitz เคยอยู่มุมขวาบนเสมอ แล้วจู่ ๆ ถูกย้ายไปอยู่กึ่งกลางซ้ายเพราะจัดแล้วดีกว่า สำหรับคนที่เพิ่งเห็นครั้งแรกอาจช่วยได้ แต่สำหรับคนที่ดูมันมาตลอด 6 เดือน มันจะดูเหมือนเป็นของคนละอย่างไปเลย
      คล้ายกับ UI ที่หน้าตาไม่สวย ต่อให้ไม่สวย ผู้ใช้ก็ชินไปแล้ว ทันทีที่ไป “จัดระเบียบ” ก็เท่ากับทำลาย เมนทัลโมเดล ของพวกเขาและบังคับให้เรียนรู้ใหม่
    • การลงทุนเวลานั้นคุ้มค่าหรือไม่ ขึ้นอยู่กับ ขอบเขตการเข้าถึงและอายุการใช้งาน ของไดอะแกรม
      บางครั้งก็เป็นแค่สเก็ตช์เพื่อจัดระเบียบความคิด แล้วทิ้งในอีก 20 นาที
      แต่ถ้าเป็นเอกสารอ้างอิงสำหรับ onboarding หรืออธิบายระบบให้ทีมอื่นฟัง เวลาอีกหนึ่งชั่วโมงที่ใช้ทำให้เข้าใจง่ายขึ้นก็อาจคุ้มค่าเต็มที่

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

    • สงสัยว่า yEd ใช้ฟรีได้ไหม SDK ของ yWorks ที่เป็นฐานดูเหมือนจะมีราคาเป็น ตัวเลข 5 หลัก แม้ใช้โดยนักพัฒนาคนเดียวบนเว็บไซต์เดียว ถ้ามีลูกค้ามาเกือบ 20 ปี ก็น่าจะเป็นเครื่องมือที่ทรงพลังพอสมควร
    • ใช้เหมือนกัน ไม่มีเหตุผลต้องวาดเอง
      แค่ดึงความสัมพันธ์ออกมาเป็น TGF แล้วนำเข้า จากนั้นใช้เลย์เอาต์แบบลำดับชั้นก็พอ
      รูปแบบ from, to, relation ก็เพียงพอแล้ว
    • ด้วยเหตุผลคล้าย ๆ กัน ผมใช้ OmniGraffle

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

    • บางครั้งการรักษาระดับนามธรรมให้สม่ำเสมอก็ยากจริง ๆ โดยเฉพาะใน ไดอะแกรมโครงสร้างพื้นฐาน ที่มักห้ามใจไม่ให้ใส่รายละเอียดในระดับต่าง ๆ เพิ่มลงไปได้ยาก
      อยากมีเครื่องมือที่ซูมเข้าไปในไดอะแกรมได้ง่าย ๆ เหมือนแอนิเมชันซูมไม่รู้จบ

  • เร็ว ๆ นี้จะเปิดตัว https://VisualFlows.io v1.0
    สามารถสร้างแผนที่ “สถาปัตยกรรม” แบบแอนิเมชันของ SaaS บริษัทแม่ได้ในไม่กี่นาที: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    ฟีเจอร์หลักได้แก่ Smart Sections, Smart Edges, Smart Node Deletion, โหมดมืด/สว่าง, การ embed, ลากแล้ววางรูปภาพ/SVG/GIF, ไอคอน AWS/Windows/Google และ Markdown ที่มีกำหนดมาในสัปดาห์หน้า เป็นต้น
    ดู Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • อยากรู้ว่าเหตุผลอะไรที่ควรใช้ตัวนี้แทน https://whimsical.com ที่เป็นผู้ใหญ่มากกว่าและมีสุนทรียะแบบเดียวกัน

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

    • ผมก็ทำแบบนี้เหมือนกัน การเขียนโค้ดสำหรับผมเป็น งานเชิงภาพ อยู่มาก อธิบายได้ยากนอกจากคำว่า “flow” ถ้าโค้ดไม่มี flow ก็รู้สึกไม่พอใจ
      เวลาเห็นเพื่อนร่วมทีมที่ดูเหมือนไม่มีเซนส์ด้านภาพของโค้ดแล้วผมรู้สึกงง เช่น ไม่เว้นบรรทัดว่างระหว่างท้ายฟังก์ชันกับการประกาศฟังก์ชันถัดไป หรือเขียนพารามิเตอร์ใน function signature แบบบรรทัดละตัวบ้าง หลายตัวต่อบรรทัดบ้างสลับไปมา มันสะดุดตามากสำหรับผม แต่พวกเขาดูไม่สนใจ
    • แม้จะไม่ได้แชร์ให้ใคร กระบวนการคิดเรื่องลำดับของบล็อกและองค์ประกอบบนหน้าก็ทำให้ต้องคิดถึงโครงสร้างที่ใหญ่กว่าและ dependency ต่าง ๆ เอง ช่วยได้มหาศาล
    • ตอนทำ network diagram ด้วย Visio ก็รู้สึกแบบเดียวกัน กลายเป็น โหมด Steve Jobs แล้วหมกมุ่นกับรายละเอียดเล็ก ๆ
      บางครั้งก็ใช้เวลา แต่มีความรู้สึกเหมือนบางอย่างได้รับการเติมเต็ม รู้ตัวว่ามีพรสวรรค์ด้านศิลปะเชิงเทคนิคอยู่พอสมควร และตอนมัธยมปลายเคยอยากเป็นช่างเขียนแบบ
    • นั่นแหละคือเหตุผลที่มี markup มันช่วยพาเราออกจาก การตกแต่งที่ไม่ก่อผลผลิต แน่นอนว่าใช้ไม่ได้กับการเขียนโค้ด
    • “การถกเถียงหมุนอยู่รอบไดอะแกรมนี้ ผู้คนเดินเข้ามาดูโดยไม่รู้ตัว คำถามถูกตอบด้วยการชี้ไปที่ไดอะแกรม เป็นระยะตลอดวัน เก้าอี้จะหันเข้าหาสิ่งที่เป็นศูนย์กลางนี้ และผู้คนจะประสานมือไว้ด้านหลังศีรษะ”
      นี่คือเป้าหมายของการทำ visualization โดยแท้

  • D2 เหมาะกับงานแบบนี้ ในบทบาทก่อนหน้านี้ผมเขียนโปรแกรมที่ parse ไฟล์ serverless.yml ทั้งหมดแล้วสร้างไดอะแกรม D2 ขนาดใหญ่โดยอัตโนมัติ
    ตอนนั้นทำ microservices บน AWS และมันดีตรงที่อัปเดตอัตโนมัติเมื่อระบบโตขึ้น ผมทำให้สามารถแยกเป็นไดอะแกรมย่อยเล็ก ๆ ตามแต่ละ subsystem ได้ เช่น แบ่งตาม SNS topic

    • ผมก็ชอบ draw.io ด้วย

  • ผมไม่เข้าใจตัวอย่างแรก ผู้เขียนพูดถึง node ที่ไม่ได้วางแผนไว้ แล้วตั้งชื่อจริง ๆ ว่า “I was unplanned” จากนั้นก็บอกว่า “ถ้าวางแผนไว้ล่วงหน้า”
    ในบริบทของไดอะแกรม ผมไม่รู้ว่าจะวางแผน สิ่งที่ไม่ได้วางแผน ล่วงหน้าได้อย่างไร สงสัยว่าหมายถึงควรเว้นพื้นที่ว่างรอบ ๆ ทุก node ให้พอหรือเปล่า
    นอกจากนี้ ข้อเสนอปรับปรุงที่ให้มาทำให้ดูเหมือนว่า “something” กับ “I was unplanned” ใช้ช่องทางหรือกลไกเดียวกันในการโต้ตอบกับ “engine”

  • ใช้ Miro อยู่ สำหรับเนื้อหาระดับสูงหรือการระดมไอเดีย เครื่องมือ post-it ก็ค่อนข้างดี แต่ไม่ได้ไปไกลเกินระดับกลาง
    หลังจากกำหนด component และ system แล้ว ก็มีเครื่องมือที่เหมาะกับงานนั้นมากกว่า

  • ถ้าเอกสารโปรเจกต์เป็น Markdown ก็ไม่ต้องใช้ไบนารีแยกต่างหาก แค่ใส่บล็อก ```plantuml เพื่อแทรกไดอะแกรมได้เลย
    ใน GitLab เวลาเปิดดูไฟล์ .md ด้วยเบราว์เซอร์ จะ render ออกมาสวยงาม GitHub ยังไม่มีฟีเจอร์นั้น