Software Architecture Diagram बनाने का तरीका (2022)

 (terrastruct.com)
3 पॉइंट द्वारा GN⁺ 2023-10-28 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • अच्छा architecture diagram सजावट से ज्यादा सही abstraction level, ताजगी और ambiguity हटाने के जरिए ideas की communication और collaboration को लंबे समय तक बनाए रखता है
  • जुड़े हुए elements को पास रखना, यानी neighbor distance minimization, बुनियादी सिद्धांत है; diagram जितना बड़ा होता है, उसे मिटाकर फिर से बनाने की iteration उतनी ही जरूरी होती है
  • symmetry सिर्फ देखने में अच्छा impression नहीं बनाती, बल्कि input और output को अलग-अलग तरफ रखने जैसे तरीकों से meaning convey करने को भी मजबूत करती है
  • shapes की center alignment बनाए रखने से जटिल concepts भी कम जटिल दिखते हैं, और नए elements जोड़ते समय पूरी layout बिगड़ती नहीं है
  • labels वाले container groups AWS और Azure जैसे environments का अंतर, ReaderWriter implementations जैसी abstractions, और Cores जैसे related objects के groups को एक नजर में दिखाते हैं

लंबे समय तक टिकने वाले diagrams की शर्तें

  • अच्छा diagram meeting खत्म होने के बाद भी मिटता नहीं है, और बाद की discussions और questions के लिए reference point के रूप में लगातार इस्तेमाल हो सकता है
  • लंबे समय तक इस्तेमाल होने वाले diagrams में कुछ common conditions होती हैं
    • elements सही abstraction level पर होने चाहिए
    • उन्हें up-to-date रहना चाहिए
    • उनमें ambiguity नहीं होनी चाहिए
  • एक ही entities और relationships को कई तरीकों से draw किया जा सकता है, लेकिन कुछ layouts project की अवधि में collaboration में मदद करती हैं और कुछ meeting खत्म होते ही गायब हो जाती हैं
  • यहां beauty से मतलब shadows या rounded corners जैसी decoration नहीं, बल्कि thoughts को effectively communicate करने वाली functional beauty है

पढ़ने में आसान layout बनाने के principles

  • neighbor distance minimize करना

    • आपस में जुड़े nodes को पास draw करना basic rule है
    • छोटे diagrams में यह आसान होता है, लेकिन diagram बड़ा होने और नई connections जुड़ने के साथ यह property आसानी से टूट सकती है
    • जैसे code में edge case मिलने पर related part को fix करते हैं, और document में missing item मिलने पर sentence को revise करते हैं, वैसे ही documentation diagrams को भी जरूरत पड़ने पर मिटाकर फिर से बनाना चाहिए
    • interview situation में फिर से draw करने की cost भारी लग सकती है, लेकिन अगर document कई लोगों या कई teams द्वारा इस्तेमाल किया जाएगा, तो iterative revision बेहतर diagram की ओर ले जाती है

  • symmetry ढूंढना

    • symmetry diagram के aesthetic impression में बड़ा योगदान देती है, और इंसानी brain चेहरे की तरह visual symmetry को पसंद करने की tendency रखता है
    • सभी nodes अपने neighbors के जितना हो सके पास हों, फिर भी symmetry की कमी हो तो diagram थोड़ा टेढ़ा-मेढ़ा लग सकता है
    • किसी node की neighbor distance थोड़ी बढ़ भी जाए, तो symmetry वाला version देखने में बेहतर हो सकता है
    • input को एक तरफ और output को दूसरी तरफ रखने का तरीका symmetry के साथ-साथ diagram के meaning को भी मजबूत करता है

  • center alignment

    • alignment diagram को साफ-सुथरा दिखाने वाला बड़ा factor है
    • साफ diagram concept को ज्यादा स्पष्ट बनाता है, और messy diagram concept को ज्यादा जटिल दिखाता है
    • अगर शुरुआत से ही खाली canvas पर shapes को randomly रख दिया जाए, तो आगे की layout भी random बने रहने की संभावना होती है
    • alignment सिर्फ दो या अधिक shapes के बीच ही meaningful होता है, इसलिए हर नया element जोड़ते समय alignment बनाए रखने से diagram naturally साफ-सुथरा बनता है
    • अक्सर symmetry से alignment पैदा होता है, लेकिन हमेशा ऐसा नहीं होता

  • container groups का इस्तेमाल

    • labels वाले कई regions में diagram को बांटने से viewer structure को ज्यादा आसानी से समझता है
    • container diagram में ये जानकारी जोड़ सकता है
      • “ये services AWS में हैं, और ये services Azure में हैं” की तरह context जोड़ता है
      • “ये सभी ReaderWriter के implementations हैं” की तरह abstraction दिखाता है
      • core 1, 2, 3, 4 को “Cores” container में बांधने की तरह related objects को group करता है

अगले भाग में जारी रहने वाले items

  • Part 2 में ये topics जारी रहेंगे
    • edge paths draw करना
    • label size और position
    • colors
    • icons

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2023-10-28
Hacker News टिप्पणियाँ

  • मैं D2 से डायग्राम बनाना पसंद करता हूँ. यह mermaid.js जैसा है, लेकिन इसमें formatting options ज़्यादा हैं, और निजी तौर पर मुझे इसकी syntax भी बेहतर लगती है
    इस पर मैंने एक छोटा लेख भी लिखा है: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • मेरा मानना है कि डायग्राम सुंदर नहीं होने चाहिए. उदाहरण के लिए, रंगों का इस्तेमाल सौंदर्य या कलात्मक पसंद के लिए नहीं, बल्कि अर्थ संप्रेषित करने के लिए होना चाहिए
      मुझे पता है कि बदसूरत software diagram देखना आनंददायक नहीं होता, लेकिन सजावट करना line graph में curves डालने जैसा है. देखने में अच्छा लग सकता है, पर जो data दिखाना है उसी में बाधा डालता है
    • मैंने उदाहरणों को आज़माया और वे वाकई शानदार थे, लेकिन मार्गदर्शन के विपरीत वे बाएँ से दाएँ नहीं बल्कि ऊपर से नीचे render हुए
      मैंने पहला उदाहरण x -> y को SVG में render किया, फिर केवल SVG को browser में खोला, और output alignment कैसे बदलें यह पूरे दस्तावेज़ में ढूँढा लेकिन नहीं मिला
      दस्तावेज़ और वास्तविक परिणाम अलग होने की वजह से मैंने इसका उपयोग बंद कर दिया. "d2lang connection left to right" खोजकर मैं https://d2lang.com/tour/layouts/ तक पहुँचा, लेकिन लगता है कि overview दस्तावेज़ से वहाँ लिंक नहीं है, इसलिए अगर इसे जोड़ा जाए तो आने वाले लोगों के लिए मददगार होगा
    • https://flowchart.fun/ ने system process को समझने के लिए flowchart बहुत तेज़ी से बनाने में मदद की. इसकी सबसे अच्छी बात यह थी कि यह सहज था और तेज़ी से iterate किया जा सकता था, और styling के लिए custom CSS भी काफ़ी उपयोगी था
      flowchart के मामले में, अब तक इस्तेमाल किए गए text-based diagram tools में यह सबसे आसान और तेज़ tools में से एक लगा
    • D2 में बहुत अच्छा layout engine tala है, लेकिन उसे इस्तेमाल करने के लिए paid license चाहिए. बाकी दो engines उतने अच्छे नहीं हैं
    • मुझे mermaid पसंद है और मैं इसे अक्सर इस्तेमाल करता हूँ, लेकिन अब D2 भी देखना पड़ेगा. Declarative diagrams विचारों को पढ़ने में आसान रूप में पकड़ने और उन्हें दूसरे text की तरह version control करने की सुविधा देने वाला एक शक्तिशाली tool हैं

  • जैसे ही system बदलना शुरू होता है, सुंदर diagram को बनाए रखना बहुत कठिन हो जाता है. ज़रा सोचिए कि पहले से जटिल diagram के बीच में एक नया box जोड़ना है; सब कुछ फिर से align करने में एक घंटा लग सकता है
    2020s के developer का समय शायद diagram को code के रूप में संभालने में लगाना बेहतर होगा: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • मैं हमेशा मज़ाक में कहता हूँ कि diagram बनाने का 10% हिस्सा असली diagram बनाना है, और 90% arrows align करना है
      लेकिन अब लगता है कि यह मज़ाक सच ही है
    • मैंने structurizr.com में import और display करने के लिए C4 model maintain किया था, और सच कहूँ तो वह मज़ेदार नहीं था. सिर्फ code से वह सहज समझ और पूरा overview नहीं मिलता जो diagram से मिलता है, और तेज़ local preview भी नहीं था, इसलिए code को server पर push करना पड़ता था
      इससे भी बुरा यह था कि नया box जोड़ने पर आम तौर पर सभी arrows को फिर से align करना पड़ता था. नतीजा यह हुआ कि diagram लगातार up to date नहीं रह पाए
      sequence diagram के लिए plantML इस्तेमाल करने पर अनुभव बेहतर था. काम खुद आसान था, इसलिए interpreter का output अक्सर manual हस्तक्षेप के बिना ही उपयोगी होता था
    • लेख में भी यह बात है कि diagram को modify करने में बहुत समय लगता है. वास्तव में ऐसा है, और अच्छा होगा अगर कोई standardized schema को ठीक से follow किया जा सके और tool auto-formatting option दे
    • जब आप elements को इधर-उधर ले जाकर फिर से align करते हैं, तो पूरे diagram को दोबारा सीखना पड़ता है. अगर frobnitz हमेशा ऊपर दाईं ओर रहता था और अचानक alignment के लिहाज़ से बेहतर होने के कारण बाईं मध्य तरफ़ चला जाए, तो पहली बार देखने वाले के लिए यह मददगार हो सकता है, लेकिन जो व्यक्ति इसे 6 महीने से देख रहा है उसके लिए यह पूरी तरह अलग चीज़ लगती है
      यह बदसूरत UI जैसा है. बदसूरत होने पर भी उपयोगकर्ता उससे पहले ही परिचित हो चुके होते हैं. जैसे ही आप उसे “साफ़-सुथरा” करते हैं, आप उनका mental model तोड़ देते हैं और उन्हें फिर से सीखने पर मजबूर करते हैं
    • यह समय निवेश मूल्यवान है या नहीं, यह diagram की reach और lifespan पर निर्भर करता है
      कभी-कभी यह सिर्फ़ विचारों को व्यवस्थित करने के लिए बनाई गई ऐसी sketch होती है जिसे 20 मिनट बाद फेंक देना है
      लेकिन अगर यह onboarding या किसी दूसरी team को system समझाने के लिए reference material है, तो उसे अधिक समझने योग्य बनाने में लगाया गया एक घंटा पूरी तरह वाजिब हो सकता है

  • ऐसी चीज़ें बनाते समय मैं yEd इस्तेमाल करता हूँ. चाहे boxes और arrows को पूरी तरह बेतरतीब डाल दूँ, menu में कुछ clicks से वह उन्हें अपने आप व्यवस्थित कर देता है
    हालाँकि कुछ समझौते करने पड़ते हैं. box के अंदर box हमेशा अच्छे से नहीं बनते. फिर भी इससे documentation कहीं तेज़ी से हो जाती है, और कुछ बार करने के बाद समझ आ जाता है कि क्या अच्छा काम करता है और क्या नहीं, इसलिए मेरे लिए यह ठीक-ठाक संतुलन है

    • मैं सोच रहा हूँ कि क्या yEd मुफ्त में इस्तेमाल किया जा सकता है. इसकी नींव yWorks SDK पर है, और लगता है कि एक ही website पर एक developer के इस्तेमाल के लिए भी इसकी कीमत 5-अंकीय राशि तक जाती है. अगर लगभग 20 साल से इनके ग्राहक हैं, तो यह काफ़ी दमदार tool होगा
    • मैं भी यही इस्तेमाल करता हूँ. खुद से खींचने का कोई कारण नहीं है
      रिश्तों को TGF के रूप में extract करके import करें, फिर hierarchical layout लागू कर दें
      from, to, relation फ़ॉर्मैट काफ़ी है
    • इसी तरह के कारणों से मैं OmniGraffle इस्तेमाल करता हूँ

  • इसमें electrical schematics, circuit diagrams और दूसरे engineering drawings से काफ़ी मज़बूत समानता है. कोई एकमात्र “सही” तरीका नहीं है
    code की तरह, अच्छी abstraction और representation चुनने की क्षमता ही समझ में आने वाले विचार और पछतावे वाली अव्यवस्थित गड़बड़ी के बीच फ़र्क करती है. यह सुंदरता या aesthetics का सवाल नहीं, बल्कि ऐसा tool है जिसमें design के लिए सक्रिय सोच और मेहनत चाहिए

    • abstraction के स्तर को लगातार एक जैसा बनाए रखना कभी-कभी सच में कठिन होता है. खासकर infrastructure diagrams में, अलग-अलग स्तर की details और जोड़ने की इच्छा को रोकना मुश्किल होता है
      काश कोई ऐसा tool हो जिसमें infinite zoom animation की तरह diagram के भीतर आसानी से zoom in किया जा सके

  • जल्द ही https://VisualFlows.io v1.0 लॉन्च करने वाले हैं
    कुछ ही मिनटों में parent company के SaaS का animated “architecture” मैप बना लिया: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    मुख्य फीचर्स हैं Smart Sections, Smart Edges, Smart Node Deletion, डार्क/लाइट मोड, embed, image/SVG/GIF drag-and-drop, AWS/Windows/Google icons, और Markdown जो अगले हफ्ते आने वाला है
    Smart Sections देखें: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • जानना चाहता हूँ कि उसी तरह की aesthetic वाला, लेकिन ज्यादा mature https://whimsical.com छोड़कर इसे इस्तेमाल करने की क्या वजह है

  • यह लेख सच में बहुत अच्छा लगा। architecture diagram बनाते समय, या docs·code लिखते समय, या काम में कुछ भी करते समय, मैं थोड़ा समय निकालकर उसे “अच्छा दिखने वाला” बनाने की कोशिश करता हूँ
    क्यों करता हूँ, यह समझाना मुश्किल है, लेकिन बाद में देखकर वह ज्यादा पसंद आता है, यह जानता हूँ
    थोड़ा डर था कि शायद यह समय का सबसे अच्छा इस्तेमाल नहीं है, लेकिन किसी ने कभी यह नहीं कहा कि ऐसा मत करो
    यह लेख इसलिए अच्छा है क्योंकि यह उस काम को, जो अब तक मैं बस एहसास के आधार पर करता था, किसी चीज़ को और सुंदर बनाने के व्यावहारिक तरीकों के रूप में समझाता है

    • मैं भी ऐसा ही करता हूँ। coding मेरे लिए काफी visual task है। इसे “flow” के अलावा किसी और तरह समझाना मुश्किल है। अगर code में flow नहीं है, तो संतोष नहीं होता
      जब टीम के ऐसे members दिखते हैं जिनमें code के visual sense की कमी लगती है, तो हैरानी होती है। जैसे function के अंत और अगले function declaration के बीच खाली लाइन नहीं छोड़ते, या function signature में कभी parameters को एक-एक लाइन में लिखते हैं और कभी कई को एक साथ, इस तरह लगातार असंगत रहते हैं। मेरी नज़र में यह बहुत उछलकर दिखता है, लेकिन लगता है उन्हें फर्क नहीं पड़ता
    • भले ही इसे किसी के साथ share न करना हो, page पर blocks और elements के क्रम पर सोचने की प्रक्रिया ही बड़े structure और dependencies के बारे में सोचने पर मजबूर करती है। यह बेहद मददगार है
    • Visio में network diagram बनाते समय भी मुझे ऐसा ही लगता है। मैं Steve Jobs mode में चला जाता हूँ और छोटी-छोटी details पर अटक जाता हूँ
      कभी-कभी इसमें समय लगता है, लेकिन कुछ भरने जैसा एहसास होता है। मुझे पता है कि मुझमें कुछ हद तक technical artistic talent है, और high school में मैं drafter बनना चाहता था
    • इसी लिए markup होता है। यह गैर-उत्पादक सजावट से बाहर निकालता है। हाँ, coding पर यह लागू नहीं होता
    • “चर्चा इस diagram के इर्द-गिर्द घूमती है। लोग अनायास पास आकर इसे देखते हैं। सवालों के जवाब diagram की ओर इशारा करते हुए दिए जाते हैं। दिन में समय-समय पर कुर्सियाँ इस केंद्रीय वस्तु की ओर मुड़ जाती हैं, और लोग हाथ सिर के पीछे बाँध लेते हैं।”
      यही visualization का लक्ष्य है

  • ऐसे काम के लिए D2 अच्छा है। पिछली role में मैंने एक प्रोग्राम लिखा था जो सभी serverless.yml files को parse करके अपने-आप एक बहुत बड़ा D2 diagram बना देता था
    हम AWS पर microservices चला रहे थे, और system के बढ़ने पर उसका अपने-आप अपडेट होना अच्छा लगता था। मैंने इसे ऐसा बनाया था कि SNS topic के आधार पर बाँटकर हर subsystem के लिए छोटे diagrams में तोड़ा जा सके

    • draw.io भी पसंद है

  • पहला example समझ नहीं आया। लेखक unplanned node की बात करते हुए उसे सच में “I was unplanned” नाम देता है, और फिर कहता है “अगर पहले से plan किया होता”
    diagram के संदर्भ में अनियोजित चीज़ को पहले से कैसे plan किया जा सकता है, यह समझ नहीं आता। क्या मतलब यह है कि हर node के आसपास काफी खाली जगह छोड़नी चाहिए?
    साथ ही, सुझाया गया improvement ऐसा दिखाता है जैसे “something” और “I was unplanned” जब “engine” के साथ interact करते हैं तो वे एक ही channel या mechanism इस्तेमाल करते हैं

  • मैं Miro इस्तेमाल करता हूँ, और high-level चीज़ों या idea sketching के लिए इसका post-it tool काफी अच्छा है। बस यह mid-level से आगे नहीं जाता
    components और systems तय हो जाने के बाद, उस काम के लिए ज्यादा उपयुक्त tools मौजूद हैं

  • अगर project documentation Markdown में है, तो अलग binary की जगह ```plantuml block डालकर diagram शामिल किया जा सकता है
    GitLab में browser से .md file देखते समय यह अच्छी तरह render होता है। GitHub में अभी तक वह सुविधा नहीं है